Updating Documentation

Introduction

The RMG Documentation is built using Sphinx and is hosted on GitHub, completely independent of the main RMG website. This page provides information on updating the documentation and deploying those updates by pushing to the gh-pages branch of RMG-Py.

The documentation source consists of a few main sections, all located in the documentation folder in the main RMG-Py directory:

• source/users/rmg - RMG user's guide
• source/users/arkane - Arkane user's guide
• theory - Theory guide
• reference - API reference

Most of the documentation is hand-written, although a substantial portion of the API 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. Documentation source pages are primarily written in the reStructuredText format, which is automatically formatted into html by Sphinx. See the Sphinx documentation for help on formatting, style, cross-linking, etc.

Once you've updated the appropriate source files, 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.

Automatic documentation builds

The live version of the documentation (at http://reactionmechanismgenerator.github.io/RMG-Py/, source on the gh-pages branch) is now automatically updated upon pushes to the master branch of RMG-Py. The automatic updating is done via Travis CI and is configured via the .travis.yml file in RMG-Py.

Changing documentation from github.com

This is the easiest method of modifying the code, though you won't be able to see how your changes look on the website.

If you have GitHub pushing permissions, you can easily edit the documentation from your web browser. You should then commit the changes to a new branch (name of your choosing). When you are ready to publish, you can create a pull request to the master branch. Once the pull request is merged, then the documentation will automatically be updated and pushed to the gh-pages branch.

Building and pushing documentation

First be sure that you have installed Sphinx in your conda environment:

source activate rmg_env
conda install sphinx

To properly build the automatic portions of the API, docstrings must be included in cythonized modules. To do so, enable the embedsignature cython directive in setup.py and recompile RMG (make; make clean). This is an optional step if you're only inspecting sections in the user's guides with no plans to push.

check on local machine

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)

cd RMG-Py
cd documentation
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 privileges at github.com (push access to ReactionMechanismGenerator/RMG-Py).

one-time setup for publishing online

If publishing for the first time from this repository, and you have not setup the build directory to push to gh-pages, run the following from the documentation folder:

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.

publish online

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 sure you are compiling with cythonized docstrings, described at the top of this section.

make clean
make html

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

make publish

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.

If you obtain any errors, look at the Makefile for the commands and modify them to effectively push the documentation. For example, you may need to force push the changes after rebasing.

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 unable to utilize all your hard work.