I have managed Sphinx documentation in several companies, covering more than 100 different services in total. The Sphinx documentation site has been my desk reference for years, and TechWriters.ru also ran on this engine until August 2026. toctree, include, roles, domains, themes, build warnings, and localization are familiar from production projects rather than a five-page demo.
That experience explains the subject, not the score. The public portal and repository were reviewed as a documentation product: onboarding, structure, reference depth, examples, reuse, builds, search, versions, interface, and translation. Sphinx remains easy to love. Its own documentation also shows where a powerful engine is presented through pages from an earlier web era.
What the study examined
Snapshot: August 17, 2026. The review covers the public master site and the official repository’s doc/ tree at commit e44a40e from August 7, 2026. Deterministic counts were taken from source; editorial findings come from the rendered pages.
.rst files including release history
.rst files outside changes/
words and tokens from wc -w, excluding release history
built-in extensions enabled in conf.py
builder types documented in the reference
A compact source project covers a very large product
The source set is smaller than many product portals, yet it spans onboarding, user guidance, extension development, Sphinx’s own API, command reference, configuration, output formats, the FAQ, and the complete release history.
| Need | Section | What the reader gets |
|---|---|---|
| Start | Getting started plus a full first-project tutorial | A short orientation and a guided project with narrative and generated API documentation. [S2] |
| Use Sphinx | reStructuredText, Markdown, links, configuration, builders, domains, extensions | The operating manual from markup through themes and internationalization. [S3] |
| Extend it | Tutorials, how-tos, and extension APIs | Roles, directives, events, domains, parsers, themes, and testing. [G3] |
| Maintain the project | Community guide, contributing, release process, FAQ | Project governance and accumulated support answers, including material that now needs editorial cleanup. [S11] |
| Look up exact behavior | Commands, conf.py, extensions, roles, directives, glossary, changelog | Reference depth that exceeds most documentation sites of comparable source size. [S1] |
The maintainers use Sphinx as a test bench for Sphinx
The project goes far beyond prose and a `toctree`. Configuration and source demonstrate almost the full characteristic toolset.
Structure
[G3]35 toctree occurrences connect individual documents. The home page divides the portal into Get started, User guide, Community, and Reference.
Reuse
[S4]The corpus contains normal include directives and 31 literalinclude uses. Tutorials pull from real Python files instead of copying examples into prose.
API from code
[G2]autodoc and autosummary are enabled. The source contains 13 automodule, 75 autoclass, and 18 autofunction directives.
Cross-project links
[S9]intersphinx connects Sphinx to Python, Requests, and Read the Docs while semantic roles validate targets.
Diagrams
[G2]graphviz and inheritance_diagram document build phases, event flow, and class relationships.
Feature history
[S12]The source contains 612 versionadded, 252 versionchanged, and 18 deprecated markers beside the affected API.
Multiple outputs
[S6]The reference lists 21 builders. Project configuration prepares HTML, RTD PDF, ePub, five man pages, and Texinfo.
Strict builds
[G2]nitpicky = True, warning types, coverage statistics, and link-check settings make the documentation build a validation system.
Reuse is one reason to love reStructuredText
A shared section can appear in several guides, be bounded by markers, and vary for HTML, PDF, or a reference build. Sphinx can also pull code from source files and add project-wide material through rst_prolog and rst_epilog.
include
Insert one shared .rst fragment into several documents; start-after and end-before can select a marked section.
literalinclude
Read code from a real file and select lines or markers, reducing drift between examples and the repository.
only
Keep one source corpus while varying content by builder or project tag.
rst_prolog and rst_epilog
Add shared definitions, substitutions, and inclusions to every document.
One section, two guides
.. include:: _shared/security-note.rst
:start-after: .. security-start
:end-before: .. security-endThe _shared/security-note.rst file remains the sole source. Both pages receive the same warning, and an editor fixes it once.
Editorial score: 78 out of 100
Sphinx earns full marks for reference, reuse, and documentation engineering. Interface design and the real state of translation reduce the result far more than the content does.
78/100
The reader journey is sensible, but it starts twice
The home page separates onboarding, user guidance, community material, and reference well. New users still face both a short Getting started path and a longer Build your first project path. Both are useful, but their boundary is explained less clearly than their steps.
| Observation | Evidence | Editorial judgment |
|---|---|---|
| Strong home-page map | Four groups identify content type and expected expertise immediately. | The architecture is legible without knowing the source tree. [S1] |
| Practical tutorial | Readers build a fictional library, write narrative documentation, and generate API pages. | A sustained example beats disconnected commands. [S2] |
| Two beginner entrances | Getting started and Build your first project repeat part of the same foundation. | Label them explicitly as the fast route and full tutorial. [S1] |
| An unfinished ending | The published quickstart ends with More topics to be covered and a short topic list. | Draft residue weakens a page intended to model documentation practice. [S1] |
| Uneven editing | The home page contains Add documentation translations multiple languages. | The missing preposition is conspicuous on a documentation tool’s showcase page. [S1] |
| Ageing FAQ | The FAQ still points to Epydoc, SCons, legacy PyPI documentation hosting, and an old _gaq Google Analytics snippet. | Historical answers should be separated from current troubleshooting. [S11] |
The interface displays the project’s age honestly
Persistent navigation, built-in search, the index, page source, and version selection work. The custom sphinx13 theme remains dense, long reference pages have limited visual hierarchy, and the dark Read the Docs flyout feels like a separate application layered over the site.
Works
Persistent section tree, heading anchors, general index, search, source link, and version access.
Feels old
Dense typography, small utility links, a crowded sidebar, and a separate RTD flyout.
Misleads
The language menu presents many locales as peers. Russian, German, and French were tested: none is complete. Russian and German retain almost all English body text, while French alternates translated material with English paragraphs and links.
Fix first
Show translation completeness beside each language, remove incomplete locales from the ordinary switcher, and modernize the theme without losing deep navigation or View source.
Practices worth taking into another documentation project
| Practice | What to adopt |
|---|---|
| Semantic links | Reference functions, classes, terms, and sections by identifiers rather than fragile URLs. |
| Shared fragments | Keep repeated warnings, requirements, and definitions in separate .rst files and include them. |
| Live examples | Use literalinclude from tested files instead of copying code into prose. |
| Version notes beside API | Place versionadded, versionchanged, and deprecated where readers make decisions. |
| Strict builds | Treat warnings as defects and run nitpicky, link checking, and cross-reference validation in CI. |
| Multiple outputs | Separate semantic source from the HTML theme and build PDF, man pages, or ePub when audiences need them. |
| Honest localization | Do not present a language as complete while the selected version retains an English document body. |
Research sources
Verdict: excellent engineering inside an ageing storefront
Sphinx documents itself almost ideally at source level. A compact corpus demonstrates hierarchy, reuse, semantic cross-references, generated API material, diagrams, version annotations, link validation, and multi-channel builds. Few projects use so much of their own engine.
The main weakness is not reStructuredText or reference depth. Readers meet an old-generation interface, two competing beginner entrances, unfinished residue in quickstart, and a FAQ carrying historical technologies. The language switcher implies complete editions, although the inspected Russian, German, and French routes all remain incomplete.
The affection survives the audit. Sphinx still gives technical writers an unusual combination of exact structure, reuse, and build discipline. Its maintainers now need to apply the same engineering standard to interface renewal, editorial cleanup, and honest translation status.
Sphinx remains one of the strongest generators for complex technical documentation. Its own portal proves the system’s power while showing how engineering quality can outrun the reading experience.