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 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.txt and add the name of your file (without the suffix) to the most appropriate toctree. For the example above:

.. toctree::
   :maxdepth: 1
   :caption: User guide
   :hidden:

   prior
   likelihood
   samplers
   a-new-feature

Checking the results

The documentation is built with the documentation pixi environment. 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.

Building the full API reference takes a while. When iterating on the narrative pages, or on the docstrings of a few modules, you can build only a subset of the API pages by passing a comma-separated list of module/object prefixes:

$ make html-api API=bilby.core.prior,bilby.gw.conversion.generate_all_bbh_parameters

or skip the API reference entirely with:

$ make html-api

The result is written to ./_build/api-subset/html so that the cached full build is not invalidated.

The tutorial notebooks in examples/tutorials are executed and copied into the docs directory as part of the CI build. To include them locally, copy them into the docs directory, e.g., cp ../examples/tutorials/*.ipynb ..

Opening a pull request

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 pull request.

Using reStructured text

The help files are written in reStructured text format. To familiarise yourself with these features visit https://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 indentation. 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, code blocks must be consistently indented and separated from the surrounding text by blank lines. The same applies to lists inside docstrings.

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.