Documenting Code

A general guide for authors and developers.

As a Developer

Setup

This section is related to maintainers of the project repository. Documentation for the LamAna package uses Sphinx, readthedocs and the nbsphinx extension. These three tools give a simple documentating experience by directly rendering jupyter notebooks. Some details are written here for reference.

The critical docs file structure is present below:

docs
|
|+ _archive
|+ _images
|- conf.py
|- Makefile
|- make.bat
|- index.rst
|- *.ipynb
|- ...

Jupyter notebooks dwell in the “docs” folder. By adding the nbsphinx extension to conf.py, notebooks extant in this folder are automatically converted to html from ipynb files by running the make html build command. This setup has several benefits:

  1. Edit notebooks directly; no copies or moves required from twin files.
  2. Notebooks are rendered as-is.
  3. Timestamps and command line info can be “hidden” prior to rendering (edit the metadata).
  4. Images can pull from a single directory

Only the index.rst file uses the native reST format.

Images

Images for the entire packages are currently reserved in the ./docs/_images folder. This placement eases root access to images for any notebook. There is an “_archive” folder within used to store older versions of image files. The README in the docs folder reminds not to enumerate updated image files, otherwise notebook links will break. Rather, copy and enumerate the old file and archive for reference.

Important

Do not add spaces filenames of images. They do not render with nbsphinx.

Note

A specical “Doc builder” file is retained in the “_notebook” folder to assist in building docs.

API Docs

The sphinx.ext.autosummary documentation is followed closely to build the API Reference page. cd into the root package and run this code to update the API reference.

$ sphinx-api -f -o ./docs/generated .

You can optionally clean the build and make a new one afterwards.

$ make clean

$ make html

This will create api docs or “stubs” for all modules found in your package and store them in the “generated” folder. This folder appears to be important for linking object rendered by autosummary to their appropriate api doc. (Projects like seaborn and pandas seem to gitignore this folder and its contents). It was obeserved here that without this folder versioned, the api docs will break links.

Note

The alternative option is to figure out how to invoke the latter command on readthedocs, but at this time, that option has not been successfully executed.

The sphinx extension viewcode links to the exact code where each module is documented in the API reference. The alternative is to use the “View in GitHub” link on each page in readthedocs (not observed locally).

Note

The API Reference currently generates long list of WARNINGS when run, related to the location of the files needed to link to the reference documentation. The links seem to work despite these warnings. Alternatives are welcome.