3. Documentation

3.1. Tools

A GitHub action is run automatically to check for typographic errors in all documentation and source code in the repository using the typos tool with our typos.toml configuration file. An associated typos command line tool can also be installed locally by developers for checking eagerly for mistakes:

$ cd /path/to/POptUS
$ typos --config=typos.toml

Other useful tools are described below with regard to the particular documentation that they serve.

3.2. Guides

Both the User and Developer Guides are developed in a single Sphinx project, which resides in the docs folder, for publication via Read the Docs. The guides’ contents are assembled from files in docs and from docstrings of Python code in the package. General text is written in reStructuredText. Python docstrings should be written using the default autodoc formatting.

Manually maintaining the list of what exceptions are raised by a function or class is difficult at best since, for example, readers might reasonably assume that all possible exceptions that could be raised by a function will be noted in the function’s documentation. This would include all exceptions raised by all functions called by that function. Therefore, we do not document exceptions.

Presently, this package does not require the use of type hints. Similarly, there is no requirement to specify argument or return types in the docstring. Note that docstrings do not need to specify the default values of optional arguments since Sphinx should be able to identify this information in the code and include it appropriately in the rendered documentation.

The guides can be rendered locally in HTML format using tox

$ cd /path/to/POptUS/poptus_pypkg
$ tox -e html

with the rendered output available at docs/build_html/index.html. Similar commands will generate PDF-format output with the pdf task. The configuration for those two tasks in tox.ini can be used as a guide for working with this documentation outside of tox.

3.3. Examples

Examples are provided as a single Jupyter book document that is published on the repository’s GitHub page and that resides in the book folder. The book’s contents are assembled from files in the book folder and from Jupyter notebooks in book/notebooks. General text is written in the MyST Markdown format.

Notebooks are typically written with a focus on the presentation of content in rendered output rather than how it is presented when viewed as a Jupyter notebook in a browser. In particular, developers adjust cell metadata to hide and remove contents to improve the conciseness of the content as well as readability. Such cell configuration can also be used to hide or remove cells with commented out content (e.g., alternate configurations or techniques) that could be useful for readers who want to interact with the notebook directly to explore the example beyond the rendered content.

The book can be rendered locally using tox

$ cd /path/to/POptUS/poptus_pypkg
$ tox -e book

with the rendered book available at book/_build/html/index.html.

The Python virtual environment (venv) created by the book task not only contains all extra external dependencies needed by the notebooks, but also extra packages that can be useful for developing and reviewing notebook content. For example, a developer can create the venv cleanly, activate the venv, and use the venv for development by executing

$ cd /path/to/POptUS/poptus_pypkg
$ tox -r -e book (this creates/recreates the Jupyter book venv cleanly)
$ . ./.tox/book/bin/activate
$ cd ../book/notebooks
$ jupyter notebook

After altering notebook content, the book task can be rerun or users can manually call Jupyter book tools using the content of the book task’s specification in tox.ini as a guide.

Note that the venv also includes nbdime so that users can view diffs using

$ nbdiff-web <notebook name>.ipynb

3.4. Macro Definitions

To aid in presenting uniform content not only within each set of documents but also across all documents, a set of common macros have been defined for both documentation tools

• docs/sphinx_macros.json

• book/_config.yml

Please familiarize yourself with this list of macros before altering documentation and please use the macros throughout your changes and additions.