HOWTO: Update online docs

How to update the online Python documentation

The Python documentation is stored in the python_docs directory on the gh-pages branch. As the documentation is automatically generated from the source, a basic understanding of Sphinx is useful in performing this procedure.

  • Begin by cloning the roadrunner master branch into a directory called “roadrunner”:
git clone https://github.com/sys-bio/roadrunner.git
  • You can now begin making the desired modifications to the Sphinx sources, which will be used to build the html documentation in subsequent steps. The general procedure is to modify the .rst files in “roadrunner/wrappers/Python/doc.” Let’s say you were trying to fix issue #101 in the roadrunner project (this issue is already fixed but we’ll pretend that it’s not for the purposes of this guide). You would first go to the main Python doc page and note that “Rates of Change” (which is now renamed to “Reaction Rates”) is under the “accessing_model.html” page. This corresponds to the accessing_model.rst file in the source tree. You would therefore open this file and change
    Rates Of Change
    ---------------
    
    .. autosummary::
    
     ExecutableModel.getFloatingSpeciesAmountRates
     ExecutableModel.getReactionRates
     ExecutableModel.getNumReactions
     ExecutableModel.getReactionIds

To

  • Reaction Rates
    ---------------
    
    .. autosummary::
    
     ExecutableModel.getFloatingSpeciesAmountRates
     ExecutableModel.getReactionRates
     ExecutableModel.getNumReactions
     ExecutableModel.getReactionIds
  • Next, clone the gh-pages branch into a directory called roadrunner-gh-pages:
git clone -b gh-pages https://github.com/sys-bio/roadrunner.git roadrunner-gh-pages
  • cd into roadrunner-gh-pages/python_docs
  • Recommended: delete the subdirectory “_images/math”, as these files are generated automatically and have different names each time
  • Run sphinx-build with the following arguments (adjusting the path to roadrunner to match your clone directory above):
sphinx-build -v -b html path/to/roadrunner/wrappers/Python/doc .
  • At this point, you should be able to run “git status” to see the results of your modifications. The html documentation as well as the image assets should have been changed
  • Execute a “git push” command (from within the python_docs directory, which should be the CWD) to update the online docs