Aether Docs

This repo contains Sphinx-formated documentation for the Aether project.

Writing Documentation

Docs are generated using Sphinx with reStructuredText syntax. A cheat sheet for reStructuredText can be found here.

Building Documentation

The documentation build process is stored in a Makefile. Building docs requires Python to be installed, and most steps create a virtualenv (usually venv-docs) which contains the required tools. You may also need to install the enchant C library using your system's package manager for the spelling checker to function properly.

Run make html to generate html documentation in _build/html.

There is also a test target, make test, which will run all the following checks. This is what happens to validate a patchset.

• make lint: Check the formatting of documentation using doc8.
• make spelling: Checks spelling on all documentation. If there are additional words that are correctly spelled but not in the dictionary (acronyms, nouns, etc.) please add them to the dict.txt file, which should be alphabetized using LC_ALL=C sort
• make linkcheck: Verifies that links in the document are working and accessible, using Sphinx's built in linkcheck tool. If there are links that don't work with this, please see the linkcheck_ignore section of conf.py.

Versioning Documentation

To change the version shown on the build site, change the contents of the VERSION file to be released SemVer version. This will create a tag on the repo.

Published documentation is built from the current branch with make html.