На Sphinx я вёл документацию в нескольких компаниях — суммарно для более чем 100 разных сервисов. Сайт документации Sphinx много лет остаётся моей настольной книгой, а TechWriters.ru работал на этом движке до августа 2026 года. toctree, include, роли, домены, темы, предупреждения сборки и локализация знакомы по реальным проектам, а не по демонстрации из пяти страниц.
Личное знакомство объясняет выбор темы, но не меняет критерии. Публичный портал и репозиторий проверены как обычный документационный продукт: путь новичка, структура, справочник, примеры, переиспользование, сборка, поиск, версии, интерфейс и переводы. Sphinx здесь действительно вызывает любовь. Независимый разбор всё равно показывает места, где сильный движок обслуживается страницами из другой эпохи.
Что вошло в исследование
Срез сделан 17 августа 2026 года по ветке master, публичному порталу и исходникам doc/ в официальном репозитории. Зафиксирован коммит e44a40e от 7 августа 2026 года. Простые счётчики применялись к исходникам, а редакционная оценка выполнялась по опубликованным страницам.
файлов .rst вместе с историей выпусков
файлов .rst без каталога changes/
слов и лексем по wc -w без истории выпусков
встроенных расширений включено в conf.py
тип сборки описан в справочнике builders
Небольшой исходный проект покрывает очень большой продукт
По числу исходников документация компактнее многих продуктовых порталов. Содержание при этом охватывает обучение, пользовательское руководство, разработку расширений, API самого Sphinx, справочник команд, конфигурацию, форматы вывода, FAQ и историю выпусков.
| Задача | Раздел | Что получает читатель |
|---|---|---|
| Начать работу | Getting started и отдельный учебный проект | Быстрый обзор и последовательное создание проекта с ручным текстом и автодокументацией. [S2] |
| Использовать Sphinx | reStructuredText, Markdown, ссылки, конфигурация, builders, domains, extensions | Полный пользовательский справочник от разметки до тем и интернационализации. [S3] |
| Расширить движок | Tutorials, how-to и API расширений | Роли, директивы, события сборки, домены, парсеры, темы и тестирование расширений. [G3] |
| Поддерживать проект | Community guide, contributing, release process, FAQ | Работа с проектом и накопленная база ответов. FAQ нуждается в серьёзной редакционной ревизии. [S11] |
| Найти точное значение | Команды, conf.py, extensions, roles, directives, glossary, changelog | Справочная часть глубже и точнее большинства небольших документационных сайтов. [S1] |
Разработчики используют Sphinx как стенд для самого Sphinx
Проект не ограничивается текстом и `toctree`. Конфигурация и исходники показывают почти весь характерный набор возможностей системы.
Структура
[G3]35 вхождений toctree связывают отдельные документы в иерархию. Главная страница делит портал на Get started, User guide, Community и Reference.
Переиспользование
[S4]В корпусе найдены обычные include и 31 literalinclude. Учебники вытягивают фрагменты настоящих файлов Python вместо копирования кода в текст.
API из кода
[G2]autodoc и autosummary включены в conf.py. По исходникам найдено 13 automodule, 75 autoclass и 18 autofunction.
Ссылки между проектами
[S9]intersphinx связывает документацию с Python, Requests и Read the Docs. Роли Sphinx проверяют цели и сохраняют семантику объектов.
Диаграммы
[G2]graphviz и inheritance_diagram включены и применяются для фаз сборки, событий и наследования классов.
История возможностей
[S12]Исходники содержат 612 versionadded, 252 versionchanged и 18 deprecated. Версионная информация находится рядом с описываемым API.
Несколько форматов
[S6]Справочник перечисляет 21 builder. Конфигурация проекта отдельно готовит HTML, PDF через Read the Docs, ePub, пять man pages и Texinfo.
Жёсткая сборка
[G2]nitpicky = True, типы предупреждений, статистика coverage и linkcheck-настройки превращают сборку документации в проверяемый процесс.
Переиспользование — одна из причин любить reStructuredText
Один общий раздел можно вставлять в несколько руководств, ограничивать маркерами и собирать по-разному для HTML, PDF или справочной страницы. Sphinx также умеет подтягивать исходный код, глобальные подстановки и общие фрагменты через rst_prolog и rst_epilog.
include
Вставляет общий .rst-фрагмент в несколько документов. Параметры start-after и end-before позволяют взять только отмеченный раздел.
literalinclude
Берёт код из настоящего файла, умеет выбирать строки или маркеры и снижает риск расхождения примера с репозиторием.
only
Оставляет один источник, но меняет состав материала для разных builders или тегов проекта.
rst_prolog и rst_epilog
Добавляют общие определения, подстановки и включения ко всему набору документов.
Один раздел, два руководства
.. include:: _shared/security-note.rst
:start-after: .. security-start
:end-before: .. security-endФайл _shared/security-note.rst остаётся единственным источником. Обе страницы получают одинаковое предупреждение, а редактор исправляет его один раз.
Редакционная оценка: 78 из 100
Sphinx получает максимальные оценки за справочник, переиспользование и инженерную сборку. Интерфейс и фактическое состояние переводов снижают итог сильнее, чем содержание.
78/100
Путь читателя сделан разумно, но начинается дважды
Главная страница хорошо разделяет обучение, пользовательское руководство, сообщество и справочник. Новичок при этом видит одновременно короткий Getting started и более длинный Build your first project. Оба материала полезны, но граница между ними объяснена слабее, чем сами шаги.
| Наблюдение | Факт | Редакторский вывод |
|---|---|---|
| Сильная карта на главной | Четыре группы сразу показывают тип материала и ожидаемый уровень подготовки. | Архитектура понятна без знакомства с каталогом исходников. [S1] |
| Практический учебник | Читатель создаёт вымышленную библиотеку, пишет повествовательную документацию и генерирует API. | Сквозной пример лучше набора несвязанных команд. [S2] |
| Два входа для новичка | Getting started и Build your first project частично объясняют одни и те же основы. | Редакции стоит обозначить быстрый маршрут и полный учебный маршрут прямо в названиях и вводных абзацах. [S1] |
| Незавершённый раздел | Опубликованный quickstart заканчивается заголовком More topics to be covered и коротким перечнем тем. | Черновой хвост снижает доверие к странице, которая должна быть образцом документации. [S1] |
| Неровная редактура | На главной осталось предложение Add documentation translations multiple languages. | Пропущенный предлог особенно заметен в витрине инструмента для документации. [S1] |
| Устаревший FAQ | FAQ всё ещё ведёт к Epydoc, SCons, старой публикации PyPI и примеру Google Analytics с _gaq. | Исторические ответы следует отделить от актуального устранения проблем. [S11] |
Интерфейс честно показывает возраст проекта
Левая навигация, встроенный поиск, индекс, исходник страницы и меню версий выполняют работу. Собственная тема sphinx13 остаётся плотной, типографика и многочисленные уровни навигации требуют привыкания, а тёмная панель Read the Docs выглядит отдельным приложением поверх сайта.
Что работает
Постоянное дерево разделов, якоря каждого заголовка, индекс терминов, поиск, ссылка на исходник и доступ к версиям.
Что устарело
Слабая визуальная иерархия длинных справочных страниц, мелкие служебные ссылки, перегруженная боковая колонка и отдельный RTD-flyout.
Что вводит в заблуждение
Меню показывает много языков как равноправные варианты. Проверка русского, немецкого и французского маршрутов не дала ни одной полноценной локализации: русский и немецкий оставляют почти весь основной текст английским, французский перемежает перевод английскими абзацами и ссылками.
Что исправлять первым
Показывать статус и полноту перевода рядом с языком, убрать неполные языки из обычного переключателя, обновить тему без потери глубокой навигации и View source.
Какие практики стоит забрать в собственную документацию
| Практика | Что забрать |
|---|---|
| Семантические ссылки | Ссылаться на функции, классы, термины и разделы по идентификаторам, а не по хрупким URL. |
| Общие фрагменты | Хранить повторяемые предупреждения, требования и определения в отдельных .rst-файлах и подключать через include. |
| Живые примеры | Подключать код через literalinclude из проверяемого файла вместо ручной копии в статью. |
| Версионные пометки рядом с API | Использовать versionadded, versionchanged и deprecated там, где читатель принимает решение. |
| Строгую сборку | Считать предупреждения дефектами, включать nitpicky, linkcheck и проверку перекрёстных ссылок в CI. |
| Разные выходные форматы | Отделять семантический источник от HTML-темы и собирать PDF, man pages или ePub из того же корпуса, когда аудитории нужен другой носитель. |
| Честную локализацию | Не показывать язык как готовый продукт, пока основная часть выбранной версии остаётся непереведённой. |
Источники исследования
Вывод: сильнейшая инженерия внутри устаревшей витрины
Sphinx документирует себя почти образцово на уровне исходников. Компактный корпус демонстрирует иерархию, переиспользование, семантические ссылки, автодокументацию, диаграммы, версионные пометки, проверку ссылок и многоканальную сборку. Немногие проекты действительно используют столько возможностей собственного движка.
Главная слабость находится не в reStructuredText и не в глубине справочника. Пользователь видит интерфейс старого поколения, два конкурирующих входа для новичка, незаконченный хвост в quickstart и FAQ с историческими технологиями. Переключатель языков обещает полноценные версии, хотя проверенные русская, немецкая и французская страницы остаются неполными.
Любовь к Sphinx после проверки остаётся. Движок по-прежнему даёт техническому писателю редкое сочетание точной структуры, повторного использования и строгой сборки. Команде проекта пора применить ту же инженерную дисциплину к интерфейсу, редакционной уборке и статусам переводов.
Sphinx остаётся одним из самых сильных генераторов для сложной технической документации. Его собственный портал подтверждает мощность системы и одновременно показывает, как инженерное качество может опередить пользовательскую подачу.