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.

Changing documentation from github.com

If you have github pushing permissions, you can easily edit the documentation and commit it on the documentation branch from your web browser in this directory. You then can create a pull request to the master branch. This will provide better availability of your contribution.

If you are super confident that you will do everything properly, you can edit the gh-pages branch directly and view your changes online. Still, make sure to pull request it to master so no one accidentally deletes your effort.

Checking locally on changes

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.

adding pages in documentation

When adding a page to the documentation, you need to manually reference it from the table of contents, or people will struggle finding it. For example, if you create a file howToMakeANewFile.rst in the documentation, you will want to add howToMakeANewFile to the index.rst file which is in the same directory.

If this is not done, people will be able to utilize all your hard work.