Writing Documentation

The documentation is found in docs/source and can be written in either Markdown (MyST) or reStructuredText.

Building Locally

Note

pdflatex and graphviz are optional but recommended docs dependencies that are required to build the minimal example PDFs and certain diagrams respectively. The documentation can still be built without them however.

Run the following from the root directory to build the docs:

$ sphinx-build -v docs/source docs/_build/html

Then, use a browser to open the html files in docs/_build/html/.

Adding a New Page

docs/index.md contains a “table of contents tree” (toctree) that defines which pages are included in the top level of the sidebar.

Alternatively, you might wish to include it in a lower level, such as how the individual filters don’t appear immediately in the sidebar. See docs/filters/index.md for how this is done, and note that the file is itself in the top-level toctree.

When writing a new page, be sure to include it in a tree!

Filters

The documentation for the filters is auto-generated for each one in in2lambda/filters every time the docs are built.

The process uses data from two files present in each filter’s source code directory:

• filter.py: Provides the top-level summary via the file’s docstring.

• example.tex: This is compiled into a PDF that’s embedded into the page.

There should then be no need to write explicit documentation for any new filters since it’s all done automatically!

How the Auto-Generation Works

A script was written in docs/filters.py that generate the docs. It’s called in docs/conf.py which is loaded when building the docs. The filters script goes through each directory present in in2lambda/filters to determine the docstring (via __doc__) and compile the LaTeX file present.

Compiled PDFs are stored in docs/_static/pdfs and the generated RST docs are put in docs/filters/_autosummary. docs/filters/index.md includes these autogenerated files in the website via a table of contents tree.

Reference

The CLT reference is generated based on the output of in2lambda --help via sphinx-click.

API documentation is built based on docstrings found within the code base. This is done using sphinx.ext.autosummary.

Tip

See the Module docs and the source code buttons on its page for good examples on how to write the docstrings effectively.