Writing documentation

This is a short tutorial on how to contribute to the documentation of bilby.

Writing the basics

First, open your terminal and head to the docs directory in your clone of bilby. Once here, you’ll notice there are a number of *txt files. Each one is a page of the documentation.

Let’s say you want to write documentation about the your new feature (or update the existing documentation). Simply open a new file a-new-feature.txt in your text editor. Then add a title and some text:

A new bilby feature!

Here we'll put a description of the new feature

Next, in order to get your new page known by the rest of the documentation, open index.rst and, under toctree add the name of your file (without the suffix). For the example above:

.. toctree::
   :maxdepth: 3
   :caption: Contents:


Checking the results

You can check what this will look like by (whilst in the docs directory) running the command:

$ make html

This will create a directory ./_build/html with the documentation. To see the result, open the file ./_build/html/index.html in your browser.

Pushing your changes to master

To contribute your documentation changes, you should create a branch and add in all of the new/changed files:

$ git checkout -b adding-my-new-documentation
$ git add index.txt
$ git add a-new-feature.txt
$ git commit -m "Adding my documentation for the feature"
$ git push origin adding-my-new-documentation

Then, on the web interface create a merge request.

Using reStructured text

The help files are written in reStructured text format. To familiarise yourself with these features visit http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html.

A useful feature is the ability to format code examples. This is done through the use of :: and indendentation. For example, to make this code block:

import bilby

You would write:

to make this code block::

   import bilby

reStructured text is very powerful, but can be quite particular. For example, all code blocks must be indented by 3 spaces.

Sphinx autosummary

Most of the documentation for bilby should be written in the docstrings of the functions/classes themselves. We can add these into the online documentation using autosummary. New code should automatically be added to the API tree.