Editing documentation

It’s very easy to edit or write documentation for CoFI. Start by cloning our GitHub repository and setting up the environment, following instructions above - fork & clone and environment setup. Then head straight to the parts that you want to change, based on the mapping table below:

Table: documentation page mapping to file path

Documentation page	File location
Home	docs/index.rst
Installation	docs/installation.rst
Tutorials (front page)	docs/tutorials/scripts/README.rst
Tutorials (tutorials content)	cofi-examples tutorials/tutorial_name.ipynb
Example gallery (front page)	docs/examples/scripts/README.rst
Example gallery (examples content)	cofi-examples examples/example_name/example_name.ipynb
Frequently asked questions	docs/faq.rst
List of functions and classes (API)	docs/api/index.rst
API reference for BaseProblem	src/cofi/base_problem.py
API reference for InversionOptions	src/cofi/inversion_options.py
API reference for Inversion	src/cofi/inversion.py
API reference for InversionResult	src/cofi/inversion.py
API reference for BaseInferenceTool	src/cofi/tools/base_inference_tool.py
Change Log	CHANGELOG.md
Contribute to CoFI	docs/contribute.rst

To change the configuration of this documentation, go change the content in file docs/conf.py.

To adjust the styling of pages, modify things in docs/_static/style.css and docs/_templates.

To test the changes, go to docs directory, run make html and open the file docs/_build/html/index.html in your browser to see the changes.

reStructuredText

All of the documentation (except for the ChangeLog part), including API references, use the reStructuredText format. This is a textual file format that tends to be more powerful compared to markdown.

For the purpose of CoFI documentation, a good resource for reStructuredText syntax is the sample project (we link to the Book theme, the one this documentation uses), with the sources here to refer to.

Build locally

To generate and check documentation locally,

$ cd docs
$ make html
$ python -m http.server -d build/html

Put localhost:8000 into your browser address bar to read the generated documentation.

Updating gallery outputs

Read the Docs (RTD) has resource limits that prevent executing sphinx-gallery examples during the build. To work around this, we pre-generate gallery outputs locally using Apptainer and commit them.

1. Build the Apptainer image (if needed):

$ cd /path/to/inlab-apptainer
$ APPTAINER_TMPDIR=$PWD ./build.sh

2. Run sphinx build locally:

$ cd docs/source
$ apptainer exec /path/to/inlab.fedora.sif bash -c 'conda activate inlab && make clean html'

3. Commit generated outputs:

$ git add docs/source/tutorials/generated/ docs/source/examples/generated/
$ git commit -m "docs: regenerate gallery outputs"
$ git push

RTD will use the pre-committed outputs instead of executing examples.

Note

• The Apptainer image includes all dependencies (pygimli, pysurf96, espresso, etc.)

• RTD skips sphinx-gallery execution via on_rtd check in conf.py

• Some examples are ignored due to compatibility issues: thin_plate_inversion.py, travel_time_tomography.py