CheatSphinx Documentation generator
Light · Postcard
102 × 152 mm · PDF
Dark · Postcard
102 × 152 mm · PDF
Ink saver · Postcard
102 × 152 mm · PDF
Light · A4 landscape
297 × 210 mm · PDF
Dark · A4 landscape
297 × 210 mm · PDF
Ink saver · A4 landscape
297 × 210 mm · PDF
Light · A3 landscape
420 × 297 mm · PDF
Dark · A3 landscape
420 × 297 mm · PDF
Ink saver · A3 landscape
420 × 297 mm · PDF
Start here
sphinx-quickstart
Scaffold a project
sphinx-build -b html <src> <out>
Build the HTML
make htmlSame via the Makefile
sphinx-build -W <src> <out>
Warnings fail the build
sphinx-build -E -a <src> <out>
Full clean rebuild
sphinx-build -b linkcheck <src> <out>
Find dead links
sphinx-apidoc -o <out> <pkg>
Stub pages for a package
sphinx-build -j auto <src> <out>
Build in parallel
Concepts
- conf.py + .rst files source dir
- Doctrees cached environment
- Output html, latex, man, text...
Project setup
sphinx-quickstart
Interactive project scaffold
sphinx-quickstart -q -p <name> -a <author> -v
<ver>
Non-interactive scaffold
sphinx-quickstart --sep
Separate source/ and build/ dirs
sphinx-build --version
Show installed version
Building
sphinx-build -b html <src> <out>
Build HTML
sphinx-build -M html <src> <out>
Make-mode build, doctrees under out
make htmlBuild via generated Makefile
make cleanDelete the build directory
-WTreat warnings as errors
Combine with --keep-going on old versions to see all warnings;
always on since 8.1.
-aWrite all output files
-ERebuild environment from scratch
-j autoParallel build on all CPUs
-nNitpicky: warn on missing references
-TShow full traceback on errors
-w <file>Also write warnings to a file
-D <key>=<value>
Override a config value
Builders
-b htmlStandard HTML pages
-b dirhtmlHTML with pretty directory URLs
-b singlehtmlWhole project in one HTML file
-b latexLaTeX sources
make latexpdfBuild PDF via LaTeX
-b linkcheckCheck external links
-b dummyParse and check only, no output
-b doctestRun doctests in the docs
-b coverageReport undocumented Python objects
-b gettextExtract .pot translation catalogs
conf.py essentials
project = "<name>"
Project name
author = "<name>"
Author string
release = "<x.y.z>"
Full version, used as |release|
extensions = ["<ext>"]
Load extensions
html_theme = "<theme>"
Pick the HTML theme
html_static_path = ["_static"]
Extra static files
exclude_patterns = ["<glob>"]
Skip source files
nitpicky = TrueWarn on every missing reference
sys.path.insert(0, os.path.abspath(".."))
Make your package importable
linkcheck_ignore = [r"<regex>"]
Skip URLs in linkcheck
reST basics
Title\n=====Section heading (underline)
*em* / **strong** / ``code``
Inline markup
* item / 1. item / #. item
Bullet, numbered, auto-numbered
`text <https://url>`__
Inline external link
.. code-block:: <lang>
Highlighted code block
paragraph::Literal block follows, indented
.. image:: <path>
Insert an image
.. note::Admonition (also warning, tip...)
.. toctree::Table of contents / page tree
.. literalinclude:: <file>
Include a source file as code
Cross-references
.. _<label>:
Define a label before a heading
:ref:`<label>`
Link to a label
:ref:`text <label>`
Link with custom text
:doc:`<path>`
Link to another document
:py:func:`~pkg.mod.func`
Python object, short display
intersphinx_mapping = {...}
Link to other projects' docs
Autodoc and apidoc
extensions = ["sphinx.ext.autodoc"]
Enable autodoc
.. automodule:: <pkg.mod>
Document a whole module
:members:Include documented members
:undoc-members:
Include members without docstrings
.. autoclass:: <pkg.Class>
Document a class
:show-inheritance:
Show base classes
.. autofunction:: <pkg.func>
Document one function
autodoc_default_options = {...}
Default directive options
autodoc_member_order = "bysource"
Keep source order
autodoc_typehints = "description"
Move type hints to the body
autodoc_mock_imports = ["<mod>"]
Fake heavy imports on build
sphinx-apidoc -o <out> <pkg>
Generate stub .rst per module
sphinx-apidoc -f
Overwrite existing stubs
sphinx.ext.napoleon
Parse Google/NumPy docstrings
Recipes
sphinx-build -W --keep-going -n -b html \ docs docs/_build/htmlsphinx-quickstart -q docs -p MyPkg -a Me -v 1.0 \ --ext-autodoc --extensions=sphinx.ext.napoleonsphinx-apidoc -o docs/api src/mypkgmake -C docs htmlsphinx-build -b linkcheck docs docs/_build/lcmake -C docs latexpdfimport os, syssys.path.insert(0, os.path.abspath("../src"))extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx"]intersphinx_mapping = { "python": ("https://docs.python.org/3", None)}
