Other docs/build

Table Of Contents

Previous topic


Next topic

Sphinx Customizations/Primer

This Page

Daya Bay Links

Content Skeleton

Build Instructions for Sphinx based documentation

Who needs to build the Sphinx docs ?

The Sphinx based documentation is built automatically by the dybinst slave, thus latex source editors need not build the Sphinx docs themselves. Committed latex sources should be automatically converted at the next slave build. However usage of latex commands/environments unknown to the converter will break the build.

People using the Autodoc : pulling reStructuredText from docstrings feature or those wishing to make significant additions to the documentation will benefit from being able to build the documentation themselves in order to achieve the desired presentation of their docstrings.

Once only virtualenv setup

  1. Get into nuwa environment and check that virtualenv is in your path:

    which virtualenv           ## should be the NuWa one
  2. Create virtual python environment, spawned from nuwa python eg:

    mkdir -p ~/v
    virtualenv ~/v/docs

For background info on virtualenv see http://www.virtualenv.org/en/latest/

Installation of Sphinx and converter into virtual python

The virtualenv comes with pip and easy_install as standard, install sphinx and converter:

. ~/v/docs/bin/activate      # activate the docs virtualenv
pip install sphinx
pip install -e git+git://github.com/scb-/converter.git#egg=converter
pip install -e git+git@github.com:scb-/converter.git#egg=converter    ## if you have the key

Several sphinx pre-requisites will be installed by pip : Pygments, Jinja2 and docutils

Additional dependencies


dependency removed

These additional dependencies on numpy and matplotlib has been removed in order to simplify the setup of a documentation building system.

Additional dependencies are required for some sphinx extensions Sandbox Testing reST/Sphinx:

pip install -E ~/v/docs -e git+git://github.com/scb-/numpy.git#egg=numpy     ## my fork of numpy
pip -v install -e svn+https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/matplotlib/#egg=matplotlib


test return to numpy original, now that my changes are integrated

Sphinx Quickstart/Configuration

The results of the sphinx-quickstart are stored in the conf.py and Makefile in the dybgaudi:Documentation/OfflineUserManual/tex directory. These have been customized, and thus the quickstart procedure should not be repeated.

Building docs

Steps to build the docs:

  1. Enter nuwa environment and activate the docs virtualpython:

    . ~/v/docs/bin/activate
    which python    ## should be ~/v/docs/bin/python
  2. Enter the tex directory:

    cd NuWa-trunk/dybgaudi/Documentation/OfflineUserManual/tex
  3. Convert tex sources into rst and then derive html, tex and pdf:

  4. Get out of the virtual python:

  5. Check the resulting documentation, at http://daya0001.rcf.bnl.gov/oum/

Partial Builds

While editing documentation it is useful to perform quick partial builds in order to quickly preview changes to parts of the document. Do so using non-default make targets such as api and sop.

Possible Problems

If on building you find the Latex error:

! LaTeX Error: File `utf8x.def' not found.

You can use a machine with a newer latex/tetex distribution, or kludge your Sphinx:

perl -pi -e 's,utf8x,utf8,'  ~/v/docs/lib/python2.7/site-packages/sphinx/ext/pngmath.py