Updating Documentation

The documentation is made by Sphinx, so look there for help on formatting, style, cross-linking, etc. Much of it is automatically generated from inspecting the Python classes, which means that you must have a fully functioning, cythonized, compiled, working copy of RMG-Py in your path to correctly generate the documentation.

You then use various make targets starting in the documentation folder to create and upload the documentation. You can learn more by reading the documentation Makefile. This is mostly like the standard sphinx makefile, but with some additional targets setup_github_pages, publish, and clean, for easily or automatically uploading the results.

First ensure you're in the right place, and have installed sphinx in your conda environment

cd RMG-Py
cd documentation
conda install sphinx

To make a local copy of the documentation to inspect it (everyone should be doing this regularly, to check that the documentation and docstrings that you write is going to be displayed correctly)

make html

then it should tell you (after some warnings) Build finished. The HTML pages are in build/html. Take a look!

You can also make latexpdf to generate a huge PDF.

Once you are satisfied with how everything looks, you may publish the HTML to the official website at http://reactionmechanismgenerator.github.io/RMG-Py. For this you will need proper priviliges at github.com (push access to ReactionMechanismGenerator/RMG-Py).

If publishing for the first time from this repository, and you don't have gh-pages (a branch of RMG-Py) locally, run command

git fetch official gh-pages
git checkout -b gh-pages official/gh-pages
git checkout -

Then set up for publishing by the command

make setup_github_pages

This will remove your build/html folder and replace it with a git repository with the gh-pages branch checked out. You only need to do this once; the following steps, however, you should do every time.

First it's a good idea to do a clean build, to remove deprecated files which won't be deleted otherwise. The clean target sets aside the git repository information but wipes everything else.

make clean
make html

Now you can publish, which can be done automatically with another make target:

make publish

(check out the Makefile to see what it's doing if you want to do it manually). It will ask for a commit message. If you wish to automate all this, eg. have a bot do it after every commit to the official master, then pass the environment variable COMMITMESSAGE so it doesn't wait for a response.

Note that the Makefile does not currently upload any LaTeXed PDFs, only the HTML.