Documentation

Documentation is important for your users and for yourself.

The documentation is built using Sphinx.

Generally, a project will have a few types of documentation:

  • A README style overview, providing an quick introduction to the package (or the subdirectory in which it is included) (a base-level README.md file is automatically generated by the cookiecutter)

  • User guide-type documentation, which explains how and why to use the package. While it may contain code examples, it’s typically more of a broad overview of package usage. For example, this page is user-guide-like documentation. A stub page for user-guide-like documentation is created in docs/source/getting_started.rst.

  • API documentation, which explains how to use the code. This is often automatically generated from docstrings in the code. A stub page for API documentation is created in docs/source/api.rst.

The template docs/ directory contains configuration files and initial stub pages for generating User Guide and API documentation using Sphinx.

Writing documentation for Sphinx

The cookiecutter creates three initial pages for your documentation, found in docs/source/:

  • index.rst: the ‘home page’, including a table of contents

  • getting_started.rst: a stub page for user-guide-like documentation

  • api.rst: a page for API documentation, using Sphinx’s autosummary extension to automatically generate documentation from your code’s docstrings, assumed to be NumPy style docstrings

These files are written in ReStructuredText format. Modify these as you see fit, and add any additional pages in this folder. See the Sphinx User Guide for help.

Configuring the documentation with Sphinx

The documentation is configured in the docs/source/conf.py file. This file contains settings for the documentation, such as the project name, version, and theme. You can also add extensions to the documentation. More information on configuring Sphinx can be found in the Sphinx documentation.

By default, the documentation is built using the MDAnalysis sphinx theme using the default template MDAKits logo and `favicon`_, and includes several useful extensions, e.g. to allow building of API docs from NumPy style docstrings.

You can customise your documentation by:

  • Add additional extensions and configuration options - see the Sphinx documentaiton.

  • Changing the theme by modifying the html_theme variable in docs/source/conf.py. You could also add custom style sheets in the docs/source/_static/ and/or template pages in docs/source/_templates/; see the respective README.md files in those folders for more information.

  • Changing the logo: You can also change the logo by either modifying the html_logo variable or by replacing the _static/logo/mdakits-placeholder-logo.png file. (This path is relative to the docs/source directory; the full path, relative to the repository root, is docs/source/_static/logo/mdakits-placeholder-logo.png.)

    Similarly, you can change the favicon by replacing the html_favicon variable or by replacing the _static/logo/mdakits-empty-favicon-template.svg file.

    You are welcome to either create an entirely custom logo and favicon or to use the provided templates. An mdakits-empty-logo-template.svg and mdakits-empty-favicon-template.svg are provided in the docs/source/_static/logo directory as templates for editing – feel free to place your logo within the gears!

Building the documentation with Sphinx

Building documentation requires different dependencies to you main package; an initial list of dependencies is provided in docs/requirements.yaml which can be used to create a new virtual environment or be added to the current virtual environment. If you documentaiton requires additional/different dependencies, include them here and in pyproject.toml.

The configuration file docs/Makefile and docs/make.bat are also provided to allow you to build your documentation.

The documentation can be build by running the following command in the docs/ directory:

$ cd docs
$ make html

This will build the documentation (as .html files) in a docs/_build/ directory; you can now view these files to see your built documention.

Hosting documentation with ReadTheDocs

If you selected the to ‘include ReadTheDocs’ when using the cookiecutter (the default option), you can now use it to automatically build and host your documentation.

ReadTheDocs is an external service. To link it to your repository, first log in to ReadTheDocs using your GitHub account. Click Import a Project on the ReadTheDocs dashboard (your project should appear here once it has pushed to GitHub). After importing you project, ReadTheDocs will build your documentation, and it will now appear online with it’s very own URL (likely at https://{repo_name}.readthedocs.io)!

We strongly recommend turning on building documentation for your pull requests to check and preview your docs. To do so:

  1. Go to the Admin tab

  2. Go to Advanced Settings

  3. Tick the “Build pull requests for this project” checkbox

  4. Scroll down and remember to click “Save”!

A test build of the documentation will now be created and can be viewed for each PR.

Further configuration can be done on from the ReadTheDocs dashboard or in the readthedocs.yaml file - see the ReadTheDocs documentation.