Skip to content

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:

Sphinx - Generated Landing Page for Documentation Site

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/miniconda:4.7.12
  script:
  - conda env update -f {{cookiecutter.repo_name}}-conda-env.yaml
  - conda init bash
  - source ~/.bashrc
  - conda activate {{cookiecutter.repo_name}}
  - sphinx-apidoc -f -o docs src
  - sphinx-build -b html docs public
  artifacts:
    paths:
    - public
  only:
  - main
...

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

Reference(s):