Documentation¶

The boilerplate packages generated by the template are populated with some NumPy formatted docstrings. What we can do with this is to observe how documentation can be automatically generated using Sphinx, with the aid of the Napoleon extension. Let's build the HTML asset for the documentation:

# From the root folder
conda activate {{cookiecutter.repo_name}}
sphinx-apidoc -f -o docs src
sphinx-build -b html docs public

Open the file public/index.html with your browser and you will be presented with a static site similar to the one shown below:

Browse through the site and inspect the documentation that was automatically generated through Sphinx.

GitLab Pages¶

Documentation generated through Sphinx can be served on GitLab Pages, through GitLab CI/CD. With this template, a default CI job has been defined in .gitlab-ci.yml to serve the Sphinx documentation when pushes are done to the main branch:

...
pages:
  stage: deploy-docs
  image:
    name: continuumio/miniconda3:23.10.0-1
  before_script:
    - source activate ./conda/{{cookiecutter.repo_name}}
    - pip install -r docs-requirements.txt
  script:
    - sphinx-apidoc -f -o docs src
    - sphinx-build -b html docs public
  artifacts:
    paths:
    - public
  only:
    - main
  needs:
    - test:conda-build
...

The documentation page is viewable through the following convention: <NAMESPACE>.gitlab.aisingapore.net/<PROJECT_NAME> or <NAMESPACE>.gitlab.aisingapore.net/<GROUP>/<PROJECT_NAME>.