Documentation

Hide code cell content

 
import mmf_setup;mmf_setup.nbinit()
import logging;logging.getLogger('matplotlib').setLevel(logging.CRITICAL)
%matplotlib inline
import numpy as np, matplotlib.pyplot as plt

This cell adds /home/docs/checkouts/readthedocs.org/user_builds/wsu-phys-581-computation/checkouts/latest/src to your path, and contains some definitions for equations and some CSS for styling the notebook. If things look a bit strange, please try the following:

  • Choose "Trust Notebook" from the "File" menu.
  • Re-execute this cell.
  • Reload the notebook.

Documentation#

Documenting your code is crucial, both for others and for yourself. Here we consider two types of documentation:

  • User Guide: This type of documentation should demonstrate how your code works. Here we will include a Developer Guide as part of this, which should describe the architecture and design choices underlying your code. We will build this documentation using MyST MD (or Jupyter Book 2, which is just a lightweight skin and default configuration on top of MyST MD.)

    I have been using this style of documentation in each of the sub-projects for the course. For example:

    Caveats: This is the future and the core focus of the Executable Books team, but is still under heavy development and has known limitations such as the [missing support for API documentation][mystmd#125]. I have also had issues executing code on GitLab Pages: see mystmd#2472.

  • API Documentation: This type of documentation is extracted from the code itself (i.e. docstrings, function signatures etc.) although it may be customized. This should be a complete reference of the actual code.

    For now we must do this with [Juypter Book 1][] or Sphinx, but at some point in the near future, you should be able to include this in your Jupyter Book 2 documentation (see issue mystmd#1259).

    I have been using this style of documentation for the actual course documentation:

    Caveats: This uses Jupyter Book 1 which is in maintenance mode. It also requires significantly more configuration than MyST MD.

MyST MD#

Here are some notes about using MyST MD. Right now it is mainly a collection of things I would like to know how to do.

Offline?#

How do we work offline? Specifically, we must ensure that we use a static version of the MathJaX or KaTeX libraries. (I know how to do this with Jupyter Book 1 – see conf.py.)

MathJaX#

MathJaX and KaTeX are the two primary libraries for rendering mathematics in HTML. Current trends are to prefer KaTeX for its speed and ease of maintenance and MyST MD follows this trend.

However, MathJaX is still used in Jupyter notebooks, so if you work with these, you might have a lot of equations that don’t work with KaTeX. In this case, you have a couple of options:

  1. Reworking your equations so that they work with with KaTeX. This is probably the best long-term approach, but can mean you are trying to support a subset of features that work in both KaTeX and MathJaX. The jupyterlab-katex extension might help (have not tried yet).

  2. Jupyter Book 1 uses MathJaX, so you could switch to that. This is not ideal because development has stopped there (they are just maintaining) and future efforts will focus on [Jupyter Book 2.

  3. As of Nov 2025, there is talk of allowing MathJaX rendering MathJaX (see issue mystmd#2442. Apparently there is a way to exploit the fact that Jupyter outputs MathJaX, but I have not figured that out yet.

Contents