CGAT scripts 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.
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.
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.
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:
Building the documentation requires the following components: