These sections cover the basics of getting started with Sphinx, including creating and building your own documentation from scratch.

Much of Sphinx’s power comes from the richness of its default plain-text markup format, reStructuredText, along with its significant extensibility capabilities. The goal of this document is to give you a quick taste of what Sphinx is and how you might use it.

Installing Sphinx¶ Sphinx is a Python application. It can be installed in one of the ways described below. Installation methods. PyPI package. Conda package. OS-specific package manager. Linux. macOS. Windows. Docker. Installation of the latest development release. Installation from source. After installation, you can check that Sphinx is ...

2024年10月12日 · #12743: Add sphinx-build--exception-on-warning, to raise an exception when warnings are emitted during the build. Patch by Adam Turner and Jeremy Maitin-Shepard.

This file (containing Python code) is called the “build configuration file” and contains (almost) all configuration needed to customise Sphinx input and output behaviour. An optional file docutils.conf can be added to the configuration directory to adjust Docutils configuration if not otherwise overridden or set by Sphinx.

While using sphinx.ext.autodoc makes keeping the code and the documentation in sync much easier, it still requires you to write an auto* directive for every object you want to document. Sphinx provides yet another level of automation: the autosummary extension.

In this tutorial you will build a simple documentation project using Sphinx, and view it in your browser as HTML. The project will include narrative, handwritten documentation, as well as autogenerated API documentation.

This guide serves to demonstrate how one can get started with Sphinx and covers everything from installing Sphinx and configuring your first Sphinx project to using some of the advanced features Sphinx provides out-of-the-box.

Utility functions and pytest fixtures for testing are provided in sphinx.testing. If you are a developer of Sphinx extensions, you can write unit tests with pytest. pytest configuration¶ To use pytest fixtures that are provided by sphinx.testing, add the 'sphinx.testing.fixtures' plugin to your test modules or conftest.py files as follows:

sphinx.ext.autosectionlabel – Allow referencing sections by their title; sphinx.ext.autosummary – Generate autodoc summaries; sphinx.ext.coverage – Collect doc coverage stats; sphinx.ext.doctest – Test snippets in the documentation; sphinx.ext.duration – Measure durations of Sphinx processing; sphinx.ext.extlinks – Markup to shorten ...