How to document#

Philosophy#

Our documentation is structured as follows:

Getting started: Step by step guide from installation to running an example.
User guide: Detailed explanation of what pyHiM can do and how to do it step-by-step.
Reference guide: Technical description of software, including API documentation and architecture.
Contributor’s guide: Description of project conventions and development tips.

Designed for	Learn	Work
User	Quickstart	User guide
Developer	Contributor’s guide	Reference

Build documentation#

To build pyHiM documentation locally, we use Sphinx which generates static, local HTML pages (see Sphinx section below). The documentation is automatically rebuilt by readthedocs using the github pyHiM source documentation files. This build of the documentation is hosted at Read the Docs and available online.

The documentation is placed in the /docs directory. Two types of documentations are provided by the developer:

Pure text files (preferably written in markdown).
Docstring within the source code (using NumPy style). See section below for more information.

Sphinx#

Sphinx is a documentation generator. It’s goal is to translate source documentation files into HTML static webpages. The default format for the documentation files is reStructuredText (reST), however, markdown can also be used (see section below).

We use Sphinx with these main extensions:

autodoc to automatically include documentation from docstring
napoleon to support NumPy style docstring
MyST to support Markdown-based documentation

How use reST directives in markdown with MyST#

ReST:

.. toctree::
:maxdepth: 1
:parameter_name: parameter_value

quick_install
classic_run
param_file
personalise_run

MyST:

```{toctree}
:maxdepth: 1
:parameter_name: parameter_value

quick_install
classic_run
param_file
personalise_run
```

Link a section from an other page#

[Build documentation locally](./dev_installation.md#build-documentation-locally)

Document features#

When you develop a new feature, please explain what it does and how use it in the user guide.

Comment the code#

“Code is more often read than written.”

– Guido van Rossum

Comments in code, help to understand your code in different ways:

Planning future development
Describe code, explain goal of this section
Algorithmic description
Tagging issues or improvement areas

When you comment code, be brief and focused.

Docstring#

Docstring is documentation string that describes what a public object does.

This comment should appear after the def line, so at the beginning of:

module
function
class
method

It’s the __doc__ special attribute of that object. To print it, you can use help()function.

Convention: always use """triple double quotes""".

There are two forms of docstrings: one-liners and multi-line docstrings.

One-line#

One-liners are for really obvious cases. They should really fit on one line.

For example:

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root
    ...

Multi-line#

For a stand-alone program, the docstring should document the script’s function and command line syntax, environment variables, and files… To be sufficient for a new user to use the command properly (or yourself in 2 years !).

Structure:
1. A summary line just like a one-line docstring
2. Followed by a blank line
3. Followed by a more elaborate description
On Spyder IDE and VSCode you can generate easly docstring by typing 3*"+Enter
Python Docstring Generator: useful vscode extension to comment easily (settings > docstring format > google/sphinx/numpy).
NumPy/SciPy Docstrings Example:

def extract_header(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    Parameters
    ----------
    file_loc: str
        The file location of the spreadsheet
    print_cols: bool, optional
        A flag used to print the columns to the console (default is False)

    Returns
    -------
    list
        a list of strings representing the header columns
    """
    headers = []
    do_something()
    return headers

Type hinting#

For python 3.5+ user, we can use type hinting. It’s a simple way to describe input and output, this is an example:

def hello_name(name: str) -> str:
    return(f"Hello {name}")

How to document

Contents