Documenting PyCBC code

These page contains some details of how to use the pyCBC Sphinx documentation system. This is a very similar to that used by numpy and scipy to document that code.

All code in PyCBC must be appropriately documented. If you find any documentation to be inadequate, please contact the development team, or improve yourself where possible.

Sphinx

PyCBC uses the sphinx documentation system to produce automatic documentation from all modules and functions, with a layer on top to describe the code appropriately.

The sphinx website has a nice tutorial on the reStructuredText format used for documentation.

Documenting the PyCBC package

The overview documentation pages (e.g. this page), live in the docs directory of the git repository. These pages are linked together using internal links.

For example: the file docs/index.rst file is used to build the home page for the documentation, and contains the following block:

.. toctree::
    :maxdepth: 1

    install
    documentation

The install and documentation entries refer to the install.rst and documentation.rst files in the same directory.

In order to provide readable documentation for all users, each key module in pycbc should have its own directory in docs that builds upon the automatic documentation built from its classes and functions. For example, the pycbc.frame module has it’s own documentation in docs/frame.rst that includes some custom text, and a copy of the automatic documentation from its classes and functions.

How much text goes directly into the module docstrings, and how much is abstracted into a separated rst file in the docs/ directory is a matter of personal taste, and keeping the code readable, but should have little effect on the HTML documentation.

Documenting PyCBC modules

All PyCBC modules should be documented using sphinx syntax, in the same way that matplotlib, numpy and scipy functions are listed.

The numpy github repository includes a nice style guide for documenting modules and their members using sphinx.

Documenting PyCBC scripts

Documenting command-line scripts isn’t ideal in any documentation language, including sphinx.

In PyCBC, command-line scripts in the bin directory of the git repository should be accompanied by a reStructuredText file in docs/bin.

However, at some point this directory got removed. So what is the current recommendation for documenting scripts??

This file contains an overview of what the code does, and some other information, with finally a dump of the command-line --help message via this directive:

.. command-output:: pycbc_inspiral --help