Documentation

This guide will help you maintain and build the project documentation.

Prerequisites

Python 3.6 or higher
pip (Python package installer)

Installation

Create a virtual environment:

It’s recommended to use a virtual environment to manage dependencies. Run the following commands:
```
python3 -m venv venv
source venv/bin/activate
```
Install the required packages:

If you haven’t already, install the dependencies required for building the documentation:
```
python3 -m pip install requirements.txt
```

Building the Documentation

Navigate to the `docs` directory:
```
cd docs
```
Build the HTML documentation:

Run the following command to build the HTML version of the documentation:
```
make html
```
The generated documentation will be in the _build/html directory.

Build the PDF documentation:

To build the PDF version of the documentation, run:

docker run -i -v $(pwd)/..:/app sphinxdoc/sphinx-latexpdf /bin/bash -c "
  cd /app &&
  python3 -m pip install -r requirements.txt &&
  cd /app/docs &&
  make latexpdf
"

The generated PDF will be in the _build/latex directory.

Maintaining the Documentation

Update the documentation source files:

The source files for the documentation are located in the docs/source directory. Update these files as needed.
Add new pages:

To add a new page, create a new .rst file in the docs/source directory and update the index.rst file to include a reference to the new page.
Rebuild the documentation:

After making changes to the documentation source files, rebuild the documentation to see the updates:
```
make html
```
Check for broken links:

You can check for broken links in the documentation by running:
```
make linkcheck
```

GitHub Actions Workflow

The project includes a GitHub Actions workflow that automatically builds and deploys the documentation to GitHub Pages.

The page is accessible at: demo-docs.aimodels.ca

The workflow is defined in the .github/workflows/docs.yaml file.

To trigger the workflow manually, navigate to the “Actions” tab in the GitHub repository and select the “Build and Deploy Documentation” workflow.

For more information on GitHub Actions, refer to the GitHub Actions documentation.