Updating the Documentation

Updating the Documentation#

About the cfr documentation#

cfr’s documentation is built automatically from the function and class docstrings, via Sphinx. It is therefore especially important for your code to include a docstring, and to modify the docstrings of the functions/classes you modified to make sure the documentation is current.

Updating docstrings#

You may use existing docstrings as examples. A good docstring explains:

  • what the function/class is about

  • what it does, with what properties/inputs/outputs

Updating tutorial notebooks#

To update an existing or add a new tutorial notebook, you need to edit and execute the notebook locally under the docsrc/notebooks directory, and build the documentation following the guide in the next section.

The notebooks are named following a naming convention: <topic>-<details>.ipynb For instance, the <topic> can be climate, proxy, psm, lmr, graphem, and pp2k, and the <details> can be a keyword of your notebook, something like ppe-pages2k. Note that if <topic> is test, the notebook will only be for a temporary test and will be ignored for building.

In the notebook, please make sure the below block is executed in the first cell so that the cfr version, an important message for the users, will be printed out:

import cfr
print(cfr.__version__)

To include a new notebook into the User Guide, you need to edit the corresponding .md files to include the relative path to your notebook. For instance, if the new notebook is about proxy system modeling, then edit docsrc/v2024/ug-psm.md and add the relative path to your notebook under the existing ones.

Building the cfr documentation#

From the repository root, run:

bash docsrc/build.sh

This may require installing other sphinx-related packages and pandoc. One may install them via the below command:

pip install sphinx nbsphinx sphinx-book-theme myst-parser sphinx-copybutton sphinx-design

Previewing the cfr documentation#

After building, preview locally:

python -m http.server -d _site 8000

Then open http://localhost:8000 in a browser.

Pushing your changes#

This step is same as the step when you push your changes with the codebase, see Pushing your changes.

Contents