This is a short tutorial on how to contribute to the documentation of
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
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,
index.rst and, under
toctree add the name of your file (without
the suffix). For the example above:
.. toctree:: :maxdepth: 3 :caption: Contents: likelihood samplers writing-documentation a-new-feature
Checking the results
You can check what this will look like by (whilst in the
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:
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.
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.