How to use Sphinx to document#

If you want to know how the following features are implemented, you can just click Page source below in the footer to see the source markdown file. For any questions and comments, please leave them in the comment box at the end.

Console#

$ mkdir doc-example
$ cd doc-example
$ sphinx-quickstart

You probably noticed that there’s a handy Copy button when you hover around the block. To enable this feature, you need pip install sphinx-copybutton, then enable it in conf.py by adding to the extension list.

extensions = [
    # ... your other extensions ...
    "sphinx_copybutton",
]

Latex equation#

Make sure the conf.py file has this setting, which will auto-number the equations.

extensions = [
    "myst_parser",
]

myst_enable_extensions = [
    "amsmath",
    "dollarmath",
]

math_number_all = True

This is inline math \(E=mc^2\), and here is a separated one as shown in equation (1).

(1)#\[ e^{i\theta} = \cos(\theta) + i\sin{\theta} \]

You can also use an inline dollar symbol to write an equation like this \(a^2 + b^2 = c^2\), or separated equations like this.

(2)#\[ \ln(1+x) = x - \frac{1}{2}x^2 + \frac{1}{3}x^3 - \frac{1}{4}x^4 + \frac{1}{5}x^5 - \frac{1}{6}x^6 + \cdots \]

Equation (2) excited Newton for two reasons. First, they could be used to speed up calculations enormously, and second, they were relevant to a controversial problem in music theory ha was working on: how to divide an octave into perfectly equal musical steps without sacrificing the most pleasing harmonies of the traditional scale [1].

Image with caption#

We can use the following way to add an image with a caption. The grammar is different from the common Markdown format. With numfig = True in conf.py, figures will be automatically numbered across all documents in the toctree (not per-document), and you can reference them using {numref}.

../_images/Github-Workflow-2.png — Fig. 1 This is a test to add an image with a caption.#

As shown in Fig. 1, the figure is automatically numbered. Note that Sphinx numbers figures continuously across all documents in your documentation (like chapters in a book), so this might not be Figure 1 if there are figures in earlier documents. To reset the figure number for each page, I created an extension doc/_extensions/per_page_numfig.py, which can be found here. If you enable it in conf.py like extensions = ['_extensions.per_page_numfig'], the figure numbers for all the figures would be correct.

Information box#

Note

This is a note.

Tip

This is a tip.

Warning

This is a warning.

Citation#

You can cite other papers easily. For example, I published my first research paper in 2020, which uses a neural network to fit a function of the structure factor of polymer systems [2]. Make sure conf.py has the following lines.

extensions = [
    # ...
    'sphinxcontrib.bibtex'
    ]
bibtex_bibfiles = ["ref.bib"]

References#

[1]

Steven H. Strogatz. Infinite Powers: How Calculus Reveals the Secrets of the Universe. Houghton Mifflin Harcourt, Boston, 2019. ISBN 978-1328879981.

[2]

Jie Huang, Shiben Li, Xinghua Zhang, and Gang Huang. Neural network model for structure factor of polymer systems. The Journal of Chemical Physics, September 2020. URL: http://dx.doi.org/10.1063/5.0022464, doi:10.1063/5.0022464.