sphinx-codeautolink makes code examples clickable by inserting links from individual code elements to the corresponding reference documentation. We aim for a minimal setup assuming your examples are already valid Python. Click any names in the example below for a demonstration:
import lib
knight = lib.Knight()
while knight.limbs >= 0:
print(knight.taunt())
knight.scratch()A directive to create a table of references from code examples to a single definition is also provided, which can also be integrated with autodoc entries. For example, .. autolink-examples:: lib.Knight produces:
lib.Knight
Integration with intersphinx is seamless:
import numpy as np
from matplotlib import pyplot as plt
x = np.linspace(0, 2 * np.pi, 100)
plt.plot(x, np.sin(x))
plt.show()
sphinx-codeautolink can be installed from the following sources:
$ pip install sphinx-codeautolink
# or, alternatively:
$ conda install -c conda-forge sphinx-codeautolinkTo enable sphinx-codeautolink, modify the extension list in conf.py. Note that the extension name uses an underscore rather than a hyphen.
extensions = [
...,
"sphinx_codeautolink",
]That's it! Now your code examples are linked. For ways of concatenating multiple examples and setting default import statements among other things, have a look at the reference documentation.
sphinx-codeautolink elsewhere:
For a more thorough explanation, see about.
- Only works with HTML documentation
- Only processes literal blocks, not inline code
- Doesn't run example code
- Parsing and type hint resolving is incomplete
The inspiration for sphinx-codeautolink came from seeing similar awesome docs generated by Sphinx-Gallery! Their source was also immensely helpful to read when I was stumbling through Sphinx and docutils. If you have a folder full of example Python scripts you'd like to include in your documentation, you'll not be disappointed in their offer.
release_notes reference about
examples example_library