Documentation

Overview

cgat.tools.and modules use sphinx for documentation. The philosophy is to maintain documentation and code together. Thus, most documentation will be kept inside the actual scripts and modules, supported by overview documents explaining usage and higher level concepts. See the Style Guide on how to write documentation.

Building the documentation

CGAT’s documentation lives in the doc directory of the repository. To build the documentation, enter the doc directory and type:

make html

The output will be in the directory _build/html.

Note

Each script, module and pipeline needs to be importable, i.e, the following must work:

python -c "import pipeline_mapping"

Especially in pipelines some care is necessary to avoid failing with an error if no input or configuration files are present.

The page coverage page lists undocumented functions and classes. To update this information, you must set the COMPUTE_COVERAGE variable when building the documentation:

make html COMPUTE_COVERAGE=1

Writing documentation

sphinx documentation is written in Restructured Text. A useful primer is here.

Some specifics for the CGAT code base are:

  • Refering to a separate script can be done using the :doc: directive, for example:

    :doc:`scripts/bed2summary`
    

    Note that the path relative to the current directory needs to be supplied.

  • Glossary terms (:term:) are defined in glossary.rst.

Adding documentation

In order to add a new script, module or pipeline to the documentation documement, perform the following steps.

Here, we will be adding the script bed2summary.py to the documentation.

  1. Create a file doc/scripts/bed2summary.rst with the following contents:

    .. automodule:: bed2summary
    
    .. program-output:: python ../scripts/bed2summary.py --help
    

    This will build the documentation within the bed2summary script and add the command line help to the document.

  2. Add an entry to doc/scripts.rst. For example:

    .. toctree::
    
       scripts/bed2summary
    

    Please add your script to the toctree of an existing group.

  3. For scripts that are part of the CGAT code collection, also add an entry into doc/CGATReference.rst.

Adding a module or pipeline is similar to adding a script, except that:

  1. the .rst file should be in doc/modules or doc/pipelines, respectively.

  2. The entry needs to be added to modules.rst or CGATPipelines.rst, respectively.

  3. no program-output is necessary.

Requisites

Building the documentation requires the following components:

sphinx

The documenation building system.

sphinxcontrib-programoutput

Adding command line output to documenation.

Trouble-shooting

The build may fail with the following error:

ImportError: Building module CGAT.NCL.cnestedlist failed: ['ImportError: /ifs/home/XXX/.pyxbld/lib.linux-x86_64-2.7/CGAT/NCL/cnestedlist.so: undefined symbol: interval_iterator_alloc\n']

In this case, remove the directory /ifs/home/XXX/.pyxbld/ and restart building the documentation:

rm -rf /ifs/home/andreas/.pyxbld/
make html