Documentation#

To build the documentation, run the following command in the project root:

python -m invoke docs.build

Usage: inv[oke] [--core-opts] docs.build [--options] [other tasks here ...]

Docstring:
  Build the documentation using Sphinx.

Options:
  -i, --ignore-warnings

Once built, you can visit the documentation locally in your browser.

Note

If you run into nitpicky errors, you can allow a more permissive documentation build with:

python -m invoke docs.build -i

Continuous integration will still run the strict build, so make sure to fix any errors before making a pull request.

Docstrings#

CapyMOA uses Sphinx to generate documentation from function, class, and module docstring comments. CapyMOA uses the sphinx/reStructuredText style of docstrings. Rather than having type information in the docstring, we prefer to use Python-type hints. This allows for better type checking and IDE support.

Here is an example of a function docstring:

class Stream:
    """A datastream that can be learnt instance by instance."""

    def __init__(
        self,
        moa_stream: Optional[InstanceStream] = None,
        schema: Optional[Schema] = None,
        CLI: Optional[str] = None,
    ):
        """Construct a Stream from a MOA stream object.

        Usually, you will want to construct a Stream using the :func:`stream_from_file`
        function.

        :param moa_stream: The MOA stream object to read instances from. Is None
            if the stream is created from a numpy array.
        :param schema: The schema of the stream. If None, the schema is inferred
            from the moa_stream.
        :param CLI: Additional command line arguments to pass to the MOA stream.
        :raises ValueError: If no schema is provided and no moa_stream is provided.
        :raises ValueError: If command line arguments are provided without a moa_stream.
        """

Notebooks#

CapyMOA documentation includes Jupyter Notebooks for tutorials, and narrative style documentation. These notebooks are run as tests to ensure they are kept up-to-date. This document explains how to run, render and test notebooks.

Added to the /notebooks directory.
Rendered to HTML and included in the documentation of the website using
To add a notebook to the documentation, add the notebook to the /notebooks directory and add the filename to the toctree in notebooks/index.rst.
Please check the notebooks are being converted and included in the documentation by building the documentation locally. See Documentation.
The parser for markdown used by Jupiter Notebooks is different from the one used by nbsphinx. This can lead to markdown rendering unexpectedly you might need to adjust the markdown in the notebooks to render correctly on the website.
- Bullet points should have a newline after the bullet point.
```
* Bullet point 1

* Bullet point 2
```

Slow Notebooks#

Some notebooks may take a long time to run. Heres how we handle slow notebooks:

The NB_FAST environment variable is set to Tue when the notebooks should be run quickly.
Add hidden cells that check NB_FAST and speed up the notebook by using smaller datasets or fewer iterations.
For example, you can add the following cell to the top of a notebook to replace some large datasets with smaller ones. You should ensure the cell is hidden on the website (See Hide Cells).
```
# This cell is hidden on capymoa.org. See docs/contributing/docs.rst
from util.nbmock import mock_datasets, is_nb_fast
if is_nb_fast():
    mock_datasets()
```

Hide Cells#

You can remove a cell from being rendered on the website by adding the following to the cell’s metadata:

"metadata": {
    "nbsphinx": "hidden"
}

Testing or Overwriting Notebook Output#

The tasks.py defines aliases for running the notebooks as tests or for overwriting the outputs of the notebooks. To run the notebooks as tests:

invoke test.nb # add --help for options

Usage: inv[oke] [--core-opts] test.nb [--options] [other tasks here ...]

Docstring:
  Run the notebooks and check for errors.

  Uses nbmake https://github.com/treebeardtech/nbmake to execute the notebooks
  and check for errors.

  The `--overwrite` flag can be used to overwrite the notebooks with the
  executed output.

Options:
  -k STRING, --k-pattern=STRING   Run only the notebooks that match the
                                  pattern. Same as `pytest -k`
  -n, --no-skip                   Do not skip any notebooks.
  -o, --overwrite                 Overwrite the notebooks with the executed
                                  output. Requires ``--slow``.
  -p, --parallel                  Run the notebooks in parallel.
  -s, --slow                      Run the notebooks in slow mode by setting the
                                  environment variable `NB_FAST` to `false`.

Manual Documentation#

Manually written documentation in the /docs directory. These can be written in reStructuredText or Markdown. To add a new page to the documentation, add a new file to the /docs directory and add the filename to the toctree in index.rst or the appropriate location in the documentation.