Working with Documentation

CGR GwasQcPipeline uses the Sphinx python documentation generator. Documentation is written in reStructuredText, a markup language similar to Markdown but with more advanced features. The sphinx documentation is stored in the docs/ folder.

.
├── docs/
│  ├── api/              # Implementation details for parsers and other helpers
│  ├── common_urls.rst   # URLs used throughout documentation
│  ├── conf.py           # Sphinx configuration file
│  ├── dev_docs/         # Development documentation
│  ├── getting_started/  # Getting started documentation
│  ├── index.rst         # Main page, if you add a new page link to it here
│  ├── Makefile          # Sphinx make file for building docs ``make html``
│  ├── reference/        # User reference material, i.e., file-type reference
│  ├── static/           # Images and styling
│  └── sub_workflows/    # Workflow documentation

However, I also embed documentation directly from the source code using keywords like .. automodule, .. pydantic, and .. click. This allows me to have details in a single location as close to the code as possible.

Note

If you add a new rst page, you must reference this page from docs/index.rst or from another page that is already linked. Otherwise, your new page will never be built.

Building Documentation

Locally

To builds documentation locally you need to have your development environment setup correctly. Then from the root folder run

make -C docs html

This will create a new folder docs/_build/html which contains the generated html pages.

My preferred way is to use VS Code with the reStructuredText plugin. Add the following to your VS Code settings.json:

{
   "restructuredtext.sphinxBuildPath": "/home/.../miniconda3/envs/cgr-dev/bin/sphinx-build",
   "restructuredtext.linter.executablePath": "/home/.../miniconda3/envs/cgr-dev/bin/rstcheck",
   "restructuredtext.confPath": "${workspaceFolder}/docs",
   "restructuredtext.languageServer.disabled": true,
}

Note

You must adjust the above paths ... to match your installation.

Then if you preview the rst file in VS Code it will auto build the docs for you.

Publishing Documentation

Publishing documentation is as easy as pushing a commit to GitHub prefixed by docs:. For example,

git add -A
git commit -m "docs: updated the documentation"
git push

This will automatically triggered a GitHub action to build and publish the documentation. This action is also triggered when creating a package release.