Build and write documentation#
The documentation contains three categories of documents:
The documentation strategy is based on the
New documents should fit into one of these categories.
We use Sphinx for documenting functionality. Install necessary dependencies to build the documentation:
pip install --editable .[doc]
If you get an error message running the above in a
zsh shell, try wrapping the last
part in a string, like
Then, build the documentation from the
cd doc make html
The documentation’s HTML pages are built in the
doc/build/html directory from files
in the reStructuredText (reST) plaintext
They should be accessible in the browser by typing
file:///your-absolute/path/to/orix/doc/build/html/index.html in the address bar.
We can link to other documentation in reStructuredText files using Intersphinx. Which links are available from a package’s documentation can be obtained like so:
python -m sphinx.ext.intersphinx https://hyperspy.org/hyperspy-doc/current/objects.inv
Writing tutorial notebooks#
Here are some tips for writing tutorial notebooks:
Notebooks (with the
.ipynbfile extension) are ignored by git (listed in the
-fgit flag must be added to
git add -f notebook.ipynbin order to update an existing notebook or add a new one. Notebooks are ignored by git in general to avoid non-documentation changes to notebooks, like cell IDs, being pushed unnecessarily.
All notebooks should have a Markdown (MD) cell with this message at the top, “This notebook is part of the
orixdocumentation https://orix.readthedocs.io. Links to the documentation won’t work from the notebook.”, and have
"nbsphinx": "hidden"in the cell metadata so that the message is not visible when displayed in the documentation.
matplotliboutput if a
matplotlibcommand is the last line in a cell.
Refer to our API reference with this MD
[Vector3d.zvector()](../reference/generated/orix.vector.Vector3d.zvector.rst). Remember to add the parentheses
()if the reference points to a function or method.
Refer to to the examples section with
Refer to sections in other tutorial notebooks using this MD
Refer to external APIs via standard MD like
The Sphinx gallery thumbnail used for a notebook is set by adding the
nbsphinx-thumbnailtag to a code cell with an image output. The notebook must be added to the gallery in the relevant topic within the user guide to be included in the documentation pages.
furoSphinx theme displays the documentation in a light or dark theme, depending on the browser/OS setting. It is important to make sure the documentation is readable with both themes. This means for example displaying all figures with a white background for axes labels and ticks and figure titles etc. to be readable.
Whenever the documentation is built (locally or on the Read the Docs server),
nbsphinxonly runs the notebooks without any cell output stored. It is recommended that notebooks are stored without cell output, so that functionality within them are run and tested to ensure continued compatibility with code changes. Cell output should only be stored in notebooks which are too computationally intensive for the Read the Docs server to handle, which has a limit of 15 minutes and 3 GB of memory per documentation build.
We also use
blackto format notebooks cells. To run the
blackformatter on your notebook(s) locally please specify the notebook(s), ie.
black *.ipynb, as
black .will not format
.ipynbfiles without explicit consent. To prevent
blackfrom automatically formatting regions of your code, please wrap these code blocks with the following:
# fmt: off python_code_block = not_to_be_formatted # fmt: on
Please see the black documentation for more details.
In general, we run all notebooks every time the documentation is built with Sphinx, to ensure that all notebooks are compatible with the current API at all times. This is important! For computationally expensive notebooks however, we store the cell outputs so the documentation doesn’t take too long to build, either by us locally or the Read The Docs GitHub action. To check that the notebooks with stored cell outputs are compatible with the current API, we run a scheduled GitHub Action every Monday morning which checks that the notebooks run OK and that they produce the same output now as when they were last executed. We use nbval for this.
The tutorial notebooks can be run interactively in the browser with the help of Binder.
When creating a server from the orix source code, Binder installs the packages listed in
environment.yml configuration file, which must include all
setup.py necessary to run the notebooks.
Writing API reference#
Inherited attributes and methods are not listed in the API reference unless they are explicitly coded in the inheriting class.