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:
- Edit notebooks directly; no copies or moves required from twin files.
- Notebooks are rendered as-is.
- Timestamps and command line info can be “hidden” prior to rendering (edit the metadata).
- 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.