Currently, we maintain a set of library and usage documentation (which is what you are reading!) that we update with each release. The following sections briefly outline how to contribute to our documentation.
All PRs which require a documentation change will not be merged until that change has been made.
Library and Usage Documentation
The library documentation is written using reStructuredText for the raw markdown and then built into web pages using Sphinx.
We’ll avoid going over reStructuredText in detail here, but here is a good reference document.
Similarly, we’ll avoid going over Sphinx in great detail as well; here is a good reference document for the most commonly used directives.
To see your changes and make sure everything rendered correctly, First activate the python virtual enivroment and run
make docs in the root
augur/ directory, and then open
docs/build/html/index.html in your web browser to view it.
$ cd augur $ python3 -m venv $HOME/.virtualenvs/augur_env $ source $HOME/.virtualenvs/augur_env/bin/activate $ make docs
Or, you can use the shortcut which does exactly this:
# to build and then open to the locally built documentation $ make docs-view
After opening it once, Make your changes in the regular
docs/source folder and just run
make docs Everytime you make any change and refresh the browser
# after opening the documentation $ make docs
Our documentation is graciously hosted by Read the Docs.
Enabled branches of the main
chaoss/augur repository will each have their own documentation, with the
main corresponding to
main on the readthedocs. The documentation will automatically be
built and deployed on a push to one of these branches or on any incoming PR, but please don’t forget to check before you push!