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 master
branch:
...
pages:
stage: deploy-docs
image:
name: continuumio/miniconda:4.7.12
script:
- conda env update -f {{cookiecutter.repo_name}}-conda-env.yml
- 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:
- master
...
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):