Writing Documentation

Writing Documentation#

Our documentation is powered by Jupyter Book and GitHub pages. Only the maintainers need to worry about GitHub pages, so this guide focuses on Jupyter Book and our documentation structure.

Summary

  • Documentation is stored as Markdown files or Jupyter notebooks in the docs/ folder.

  • Use tox -e literature,docs to compile the documentation locally.

  • Do not git add files from docs/_build/.

Jupyter Book#

Jupyter Book is “an open source project for building beautiful, publication-quality books and documents from computational material.” It allows you write technical content as Markdown files (.md) or Jupyter notebooks (.ipynb). Use a notebook if you have code that you actually want to run (e.g., in tutorials); Markdown is often sufficient and a little easier otherwise.

Documentation Structure#

All documentation is grouped in the docs/ folder. The project README.md should be kept short and refer to the official documentation.

  • docs/_config.yml: configuration for the Jupyter Book format.

  • docs/_toc.yml: documentation table of contents. You will need to modify this file if you add or delete documentation pages.

  • docs/references.bib: Bibtex citations. Cite them in the documentation with {cite}`referencekey`.

  • docs/images/: contains all static images not generated by code in a notebook. SVGs are preferable, PDFs and PNGs are probably fine.

  • docs/source/: contains all of the files with the actual written documentation. The file tree structure should be somewhat obvious from the structure of the page you’re looking at right now and from docs/_toc.yml.

  • docs/source/tutorials/: contains notebooks with full examples for specific applications.

As you can see on the left of this page, docs/source/ is organized into the following chapters.

  • Operator Inference: general exposition about the setting and methodology.

  • Tutorials: notebooks with full examples for specific applications. These should be written in a narrative style: mathematical details are good, but only when accompanied by nontechnical summaries.

  • API Reference: public function/class signatures and docstrings. Most of these pages are generated automatically (see jupyterbook.org/advanced/developers), but the index for each submodule is a notebook with demonstration code.

  • Developer Guide: instructions for developers (such as this page).

Building Documentation Locally#

From the root folder of the repository, execute tox -e docs to build the documentation. This is a shortcut for invoking jupyter-book with the right prerequisites. If any changes are made to the Literature page through modifications to docs/bib2md.py, run tox -e literature first.

The documentation is processed and copied to in docs/_build. Open the file docs/_build/html/index.html in a browser to see a preview (try Google Chrome if the file doesn’t render nicely).

Attention

Do not git add the build files from docs/_build! Only the gh-pages branch should track this folder. The .gitignore should remind you of this if you accidentally try to add them.

Sphinx Autodoc#

Jupyter Book is essentially an opinionated wrapper around Sphinx, a program for generating Python documentation. This project uses Jupyter Book with Sphinx Autodoc to automatically generate documentation straight from code docstrings. Because of our settings for the automatic documentation generation, please follow these guidelines.

  • Class docstrings should not have a “Methods” section.

  • Properties show up automatically in the documentation, but attributes created at runtime do not.

  • Use :math: environments to write actual math.

Note that docstrings must follow Sphinx syntax, not Jupyter notebook syntax. For example, use :math:\i^2 = -1`instead of\(i^2 = -1\)`.

Example: Contributing a New Tutorial#

TODO

  • Create a notebook and place it in docs/souce/tutorials/.

  • Add it to the book with docs/_toc.yml.

  • Always clear notebook outputs before git add ing.

  • Add data files to the data branch:

git checkout --orphan data
git switch data
git pull upstream data
git add mynewdatafile.npy
git commit -m "add datafile for <the tutorial>"
git push origin data

Then open a pull request to the data branch.

Helpful Jupyter Book References#

Some particularly useful pages from the Jupyter Book topic guides:

Contents