Documentation

This current documentation was created and configured using this tutorial. It’s a set of text files in Markdown (MD) or reStructuredText (RST or ReST) language.

We use Sphinx tool to generate HTML pages and ReadTheDocs to host documentation online. On ReadTheDocs, the documentation is automatically build and update when your push code on main or dev branches to GitHub repository.

Shortcut

Create a doc

Doc from code

ReST with MyST

Build locally

Isolated virtual env (similar with RTD env):

bash build_docs.sh

Development env (faster):

rm -r docs/build/html
sphinx-build -b html docs/source docs/build/html

New script

Please, follow this tutorial.

Feature enhancement

Python script

Document inside your python script.

  • Update the header docstring of the module / script

  • Link this docstring to the argparse description argument with __doc__

  • If you create a new CLI option with .add_argument(...), add a help argument.

Example:

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
This is the place of header docstring.
"""
def parse_arguments():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--z_min", help="Z minimum for a localization.")

Reliability status

Choose the status of your main feature (can be non-exhaustive):

  • development = no test available

  • beta-test = only manual test(s)

  • stable = automatic test(s)

Find the doc file inside docs/source/scripts/ folder.

Add just after the main title: “Reliability status: (in bolt) status value (in backtick)”

# plot_him_matrix

**Reliability status**: `stable`

Markdown script (Optional)

Document inside the markdown file linked to this script.

  • Find the doc file inside docs/source/scripts/ folder

  • Add general information or images after this block:

```{eval-rst}
.. argparse::
:ref: traceratops.plot_him_matrix.parse_arguments
:prog: plot_him_matrix
```