Updating documentation¶
The documenation is generated automatically by ReadTheDocs, and triggerd by
pushing commits to the documentation
branch.
Note that the entire documentation infrastructure only exists in the
documentation
branch: the docs
directory is not and should not
be checked into any branch other than the documentaiton branch.
Make sure you are in the documentation
branch at all times when
updating documentation. If you accidentally make changes to the code
or to other parts of the repository while in the documenation
branch, do not push your changes.
If you don’t have the documentation
branch in your repository,
use:
git checkout --track origin/documentation
Updating text¶
The documentation is contained in .rst
files in the documentation
branch.
The docs
subdirectory is only present in this branch. New documents can be added
to the source directory, and linked to the correct section (usually in index.rst
).
Once the new document (or a modified document) is ready, follow this procedure:
git checkout documentation
git pull
git add new_document.rst
git commit -m "I have added a new document"
git push
git checkout master (or develop or any other working branch)
Keeping the documentation branch up to date¶
Because the documentation uses autodoc methods (such as automodule
) to extract
doc strings from the functions and classes, it is important to keep the documenation
branch in sync with the master branch (or with any other active branch).
To to this, follow this procedure:
git checkout documentation
git pull
git rebase master (or develop or other active branches)
git push --force
git checkout master (or develop or other working branches)