---
jupytext:
formats: ipynb,md:myst
text_representation:
extension: .md
format_name: myst
format_version: 0.13
jupytext_version: 1.13.6
kernelspec:
display_name: Python 3 (phys-581)
language: python
name: phys-581
---
```{code-cell}
:tags: [hide-cell]
import mmf_setup;mmf_setup.nbinit()
import logging;logging.getLogger('matplotlib').setLevel(logging.CRITICAL)
%matplotlib inline
import numpy as np, matplotlib.pyplot as plt
```
(sec:Documentation)=
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:
* [Physics 581: Schrödinger Equation][]: See the [Physics 581: Schrödinger Equation Docs][].
* [Physics 581: Data Fitting][]: See the [Physics 581: Data Fitting Docs][].
**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:
* [Physics 581: Course][]: See the [Physics 581: Course Docs][] hosted on [Read The Docs][].
**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`.)
### Common List of Links
It is very convenient to include links in my documentation. For example, I can refer to
[MyST MD][] with the code `[MyST MD][]` if somewhere I include `[MyST MD]:
`. As I build more and more documentation, I find myself repeating
these links, violating the [DRY][] principal. Is there a common place to put these?
Some possible solutions with [MyST MD][]:
* You can define [External References][] in `myst.yml` then use the `` format:
```yaml
references:
DRY: https://en.wikipedia.org/wiki/Don't_repeat_yourself
```
* With Wikipedia entries, you can use ``:
. But I don't know how to use abbreviations for these.
:::{margin}
E.g. [CoCalc deprecated support for
MathJaX](https://github.com/sagemathinc/cocalc/issues/7903) in Oct 2024. (They have an
option to fallback if [KaTeX][] rendering fails, but this can lead to [subtle issues](https://github.com/sagemathinc/cocalc/issues/6179).
:::
### 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.
:::{margin}
There is an extension [jupyterlab-katex][] that [can also be used with version 7+
Jupyter notebooks](https://github.com/jupyter/notebook/issues/3094#issuecomment-1600287828).
:::
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](https://github.com/jupyter-book/mystmd/issues/2442#issuecomment-3566999942) to
exploit the fact that Jupyter outputs [MathJaX][], but I have not figured that out yet.
[KaTeX]:
[MathJaX]:
[External References]:
[MyST MD]:
[Jupyter Book 1]:
[Jupyter Book 2]:
[mystmd#1259]:
[mystmd#2472]:
[mystmd#2442]:
[Sphinx]:
[Physics 581: Schrödinger Equation]:
[Physics 581: Schrödinger Equation Docs]:
[Physics 581: Data Fitting]:
[Physics 581: Data Fitting Docs]:
[Physics 581: Course]:
[Physics 581: Course Docs]:
[Read The Docs]:
[known limitations]:
[DRY]:
[jupyterlab-katex]: