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 inglossary.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.
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.
Add an entry to
doc/scripts.rst
. For example:.. toctree:: scripts/bed2summary
Please add your script to the toctree of an existing group.
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:
the
.rst
file should be indoc/modules
ordoc/pipelines
, respectively.The entry needs to be added to
modules.rst
orCGATPipelines.rst
, respectively.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