Contributing documentation

The documentation lives on the cogent3.org website. There are several components involved in building the documentation across different locations. An overview of the whole process involves:

1. Writing documentation in restructured text format (.rst) on the main Cogent3 repo
2. Testing that .rst files and code is correct
3. From the compliant .rst files, generate .html files using Sphinx and a custom template
4. Finally, the website is built from cogent3.github.io

More information on the components above:

- Restructured text format
- Sphinx

Writing documentation

When adding or editing the .rst files, refer to the instructions in the specific issue you are addressing.

Some other things to consider:

• Ensure that all spelling and the heading levels are consistent with the rest of the file.
• Aim to adhere to one of the four Documentation types used in Cogent3.
• Comment on the issue if anything is unclear!

Code directives

The restructured text format allows code chunks that can be executed. All code to be executed is placed under a jupyter-execute directive. For example:

.. jupyter-execute::

    from cogent3 import load_aligned_seqs

    aln = load_aligned_seqs("data/brca1-bats.fasta", moltype="dna")
    aln

Snippets that require data should try and use existing sample files under Cogent3/doc/data. If needed, additional files can be added. But if you do add such a file, you also need to add it to Cogent3/doc/data/data_files_links.rst so it is available as a download for readers.

All other code is placed under a code-block directive.

.. code-block:: python

    from cogent3 import load_aligned_seqs

    aln = load_aligned_seqs("data/brca1-bats.fasta", moltype="dna")
    aln

Testing code in documentation

After adding or amending code in the .rst files (i.e. jupyter-execute or doctest directives), you must test that the code is correct:

$ cd Cogent3/doc/
$ ./doctest_rsts.py -f <amended_doc.rst>

If successful, you should see a completed progress bar, without any FAILED: ... messages.

Building documentation

Once all tests have passed, build the documentation with Sphinx:

$ cd Cogent3/doc
$ make html

Lastly, check that the changes look ok by opening _build/html/index.html and navigating to the edited page!

Writing docstring examples

Cogent3 includes docstring examples to inform users the various ways e.g. a function can be used. The examples also inform the acceptable input arguments and expected outputs of common use cases.

See How‐to write docstring examples for methods and functions for a guide on how to contribute docstring examples.