Documentation

Building

Building the documentation requires sphinx:

# debian/ubuntu
$ apt-get install python-sphinx
# arch
$ pacman -S python-sphinx
# generic
$ pip install sphinx

Once sphinx is installed (verify with which sphinx-build), it can be built using the Makefile:

cd docs
make

This will create html documentation under docs/_build/html/.

Structure

The documentation is structured as follows:

• conf.py - sphinx configuration, imports the globus_sdk package to use in autodoc directives and to get the package version
• index.rst - homepage, contains basic example and links to other docs
• Makefile - simplifies building the documentation in various formats. autogenerated by sphinx-quickstart, tweaked to make html the default action

In general most of the documentation should be in docstrings. Using curated rst files instead of the sphinx-apidoc command allows us to customize the structure, while still allowing most of the documentation to be automatically generated.