How‐to write docstring examples for methods and functions

Overview

"A Python docstring is a string used to document a Python module, class, function or method, so programmers can understand what it does without having to read the details of the implementation." - pandas docstring guide

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

The high-level process for writing and testing docstring examples is as follows:

1. Select a method/function to document
2. Parameters - Check the parameter definitions are clearly written and type hints are provided and correct in the function signature
3. Examples - include example usage of the method/function
4. Test the docstring examples with doctest
5. Build the documentation
6. Submit PR

Parameters

A parameters section is likely to already exist in a method/function, which outlines the different input arguments and their types.

Check that:

• All function/method arguments (parameters) are documented
• Each parameter has a clear, informative description of what it does, and the possible options if required
• Each parameter is type hinted in the function signature

For method parameters, self does not need to be included.

Note

With regards to formatting, aim to keep text within 80 columns per line

Examples

The examples section should begin with a succinct statement on what the method/function achieves. In methods, you can often obtain this information from the class docstring.

The remaining docstring should contain your individual examples.

Each working example must contain:

1. A description of what is demonstrated
2. Executable doctest code
3. The expected output

How-to determine what examples to include

First, identify working examples to include in the docstring. These should demonstrate the intended usage of the method/function and cover various inputs that can be used. A few points to consider when deciding what examples to include:

• Aim to include examples that cover the different use cases of the method/function.
• Aim to include examples that cover each parameter.
• A good first example is what users can expect when running the method/function using default values.

Tip

A good source for examples is to check the unit tests for a method/function. Tests can be found in Cogent3/tests/ under the matching module name.

Descriptions

For each example, provide a succinct and informative description of what the method/function does. Include any relevant background information to help with the understanding of concepts, or usage of the method/function.

For example, in cogent3.app.sample, the omit_degenerates() docstring contains information on degenerate characters.

How-to develop executable doctest code

We recommend you develop and test your examples interactively, such as in a Jupyter notebook. Then, transfer it over to the docstring. This is useful for identifying the expected output.

In the docstring, lines where code should be executed should begin with >>> .

>>> x = "Example text"
>>> print(x)
"Example text"

Any code that spans multiple lines must begin with ... .

>>> data = {
...     "s1": "ACTG",
...     "s2": "ACTC"
... }
>>> print(data)
'{'s1': 'ACTG', 's2': 'ACTC'}'

As shown in the examples above, you must define the expected output on the line directly after the last line of executed code. When sequences are output, use print(output.to_pretty()).

Refer to the NumPy docstring standards for more examples and formatting.

How-to test docstring examples

Important

Docstring examples must be tested and working before submitting a PR.

Once you have included docstring examples, you must test that they work. In your terminal, navigate to the folder where the module of the documented method/function is.

To test your examples, run:

$ pytest --doctest-modules -k function_name

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

How-to build documentation

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

$ cd Cogent3/doc
$ make html

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

Next steps

Once the examples are working, and the documentation is built and all looks good, you are ready to add your contribution to the Cogent3 GitHub. Refer to The development workflow for instructions on committing your changes and submitting a pull request.

When writing your commit message for docstring example contributions, you should prefix the message with the DOC: ... acronym.

Caution

Ensure that your feature branch is up-to-date with the cogent3/develop branch before submitting a PR.