Extensions

Built-in extensions

Add to conf.py:

extensions = []

sphinx.ext.autodoc – Include documentation from docstrings

In conf.py add:

import os
import sys
sys.path.insert(0, os.path.abspath(".."))
# 0 is the beginning
# relative path to docs

sphinx.ext.graphviz – Add Graphviz graphs

Install:

scoop install graphviz
dot -c
pip install graphviz
digraph foo { "bar" -> "baz"; }
graph foo { "bar" -- "baz"; }

Clickable

digraph example { a [label="sphinx", href="https://www.sphinx-doc.org", target="_top"]; b [label="other"]; a -> b; }

sphinx.ext.todo – Support for todo items

Todo

  • 🟩 Mercury

  • ✅ Venus

Third Party Extensions

Text Utility

sphinx-copybutton

Install:

pip install sphinx-copybutton

Add to conf.py:

extensions = [
...
"sphinx_copybutton",
...
]

Changing Content Programmatically

Maths Support

write LaTeX math using $$

Install:

pip install sphinx-math-dollar

Edit conf.py:

extensions = ['sphinx_math_dollar', 'sphinx.ext.mathjax']

mathjax_config = {
    'tex2jax': {
        'inlineMath': [ ["\\(", "\\)"] ],
        'displayMath': [["\\[", "\\]"] ],
    },
}

Fix:

WARNING: mathjax_config/mathjax2_config does not work for the current MathJax version, use mathjax3_config instead

Issues

Warning

quizdown stops working

Classroom

Attention

Consider just use Python’s Quizdown

Install:

pip install git+git://github.com/bonartm/sphinxcontrib-quizdown

Setup:

extensions = [
    ...,
    "sphinxcontrib.quizdown",
    ...
]