Войти или Регистрация
питон либ луна питонлиб солнце pythonlib цветок

Изменить тему

Sphinx – генерация документации

онлайн тренер по питону
Онлайн-тренажер Python 3 для начинающих

Теория без воды. Задачи с автоматической проверкой. Подсказки на русском языке. Работает в любом современном браузере.

начать бесплатно

Введение

Качественная документация — это не просто дополнение, а основа успешного проекта. Она помогает новым пользователям разобраться с API, ускоряет разработку и облегчает поддержку. Sphinx – генерация документации — это мощный инструмент, который автоматизирует создание и сборку документации из исходного кода Python.

Sphinx используется для официальной документации Python, NumPy, Django и многих других проектов. Он поддерживает как ручное написание, так и автоматическую генерацию документации из docstring.

Установка и начальная настройка

Установка Sphinx:

bash
pip install sphinx

Инициализация документации:

bash
sphinx-quickstart

Выберите опции: название проекта, автор, формат (reStructuredText), путь к исходникам и др. После этого появится структура:

objectivec
docs/ ├── _build/ ├── _static/ ├── _templates/ ├── conf.py └── index.rst

Структура проекта документации

  • conf.py — основной конфигурационный файл

  • index.rst — начальная точка документации (оглавление)

  • _build/ — каталог с готовой документацией (HTML, PDF и т.д.)

  • _static/, _templates/ — папки для стилей и шаблонов

Автоматическое документирование Python-кода

Подключите расширение:

python
# В conf.py extensions = ['sphinx.ext.autodoc']

Добавьте путь к модулю:

python
import os import sys sys.path.insert(0, os.path.abspath('../src'))

Создайте файл API-документации:

bash
sphinx-apidoc -o source/ ../src/

Это создаст .rst файлы для всех модулей.

Работа с reStructuredText (reST)

Пример синтаксиса:

rst
Пример заголовка ================ **Полужирный текст**, *курсив*, ``код``. - Список 1 - Список 2 Ссылка на `функцию <module.html#function>`_

Интеграция с Markdown и MyST

Если вы предпочитаете Markdown, установите:

bash
pip install myst-parser

Добавьте в conf.py:

python
extensions = ['myst_parser']

Теперь можно использовать .md файлы наравне с .rst.

Темы оформления и кастомизация

Установка популярной темы:

bash
pip install sphinx_rtd_theme

В conf.py:

python
html_theme = 'sphinx_rtd_theme'

Вы можете изменить:

  • Цветовую схему

  • Шрифты

  • Логотипы

  • Шаблоны навигации

Модули и расширения Sphinx

Рекомендуемые расширения:

  • autodoc — документация из docstrings

  • napoleon — поддержка Google/NumPy-style docstrings

  • viewcode — добавление ссылок на исходный код

  • intersphinx — ссылки на внешние документации

Пример:

python
extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx' ]

Связь с внешними библиотеками

python
intersphinx_mapping = { 'python': ('https://docs.python.org/3', None), 'numpy': ('https://numpy.org/doc/stable/', None), }

Теперь можно делать ссылки на внешние API:

rst
Смотрите :class:`numpy.ndarray`.

Сборка документации

Сборка HTML:

bash
make html

Сборка PDF:

bash
make latexpdf

Для Windows:

bash
.\make.bat html

Или с помощью sphinx-build:

bash
sphinx-build -b html source/ build/html

Автоматизация и Makefile

Файл Makefile позволяет автоматизировать сборку и упрощает команды. Используйте:

  • make clean — очистка сборки

  • make html — создание HTML

  • make latexpdf — создание PDF через LaTeX

Публикация документации

ReadTheDocs

  1. Зарегистрируйтесь на readthedocs.org

  2. Подключите репозиторий

  3. Убедитесь, что в проекте есть requirements.txt с sphinx

  4. ReadTheDocs сам найдёт conf.py и соберёт документацию

Альтернативы

  • GitHub Pages: загрузите docs/_build/html в ветку gh-pages

  • Netlify или Vercel: подключите как SPA/статический сайт

Интеграция с CI/CD

GitHub Actions

yaml
jobs: docs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - run: pip install sphinx sphinx_rtd_theme - run: sphinx-build -b html docs/ docs/_build/html

Sphinx и Docstrings: Google/NumPy стиль

Подключите sphinx.ext.napoleon и пишите docstring в формате:

Google style:

python
def func(x): """Суммирует числа. Args: x (int): Число Returns: int: Результат """

NumPy style:

python
def func(x): """ Суммирует числа. Parameters ---------- x : int Число Returns ------- int Результат """

Советы по структуре и организации

  • Разделите документацию на модули

  • Используйте toctree для навигации

  • Создайте glossary, faq, changelog при необходимости

  • Используйте автосодержание:

rst
.. toctree:: :maxdepth: 2 :caption: Содержание: module1 module2

Часто задаваемые вопросы (FAQ)

1. Что такое Sphinx?
Инструмент генерации документации из исходного кода Python и других языков.

2. Можно ли использовать Markdown?
Да, через myst-parser.

3. Как подключить автогенерацию?
С помощью sphinx.ext.autodoc и sphinx-apidoc.

4. Как изменить тему оформления?
Установите другую тему и укажите её в conf.py.

5. Можно ли опубликовать документацию онлайн?
Да, через ReadTheDocs, GitHub Pages, Netlify и др.

6. Как интегрировать с CI/CD?
Через GitHub Actions или GitLab CI — сборка и публикация документации возможны автоматически.

Полный справочник по работе с Sphinx — системой генерации документации для Python

Установка

bash
pip install sphinx

Для генерации PDF (опционально):

bash
sudo apt install texlive-latex-recommended texlive-latex-extra

Быстрый старт

bash
sphinx-quickstart

Этот интерактивный скрипт создаёт базовую структуру проекта:

bash
docs/ ├── conf.py # конфигурация Sphinx ├── index.rst # главная страница ├── _build/ # выходная документация ├── _static/

Команды сборки

Команда Назначение
make html Сборка HTML-документации.
make latexpdf Сборка PDF через LaTeX.
make epub Сборка ePub.
sphinx-build -b html . _build/html Ручной запуск.

Подключение автодокументации

1. Установи расширения:

bash
pip install sphinx autodoc

2. В conf.py добавь:

python
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

  • autodoc: позволяет генерировать документацию из docstrings.

  • napoleon: поддержка Google/NumPy-style docstrings.

3. В index.rst добавь:

rst
.. automodule:: your_module :members: :undoc-members:

Документация из docstring

Пример Python-кода:

python
def add(a, b): """ Сложение двух чисел. :param a: Первое число :param b: Второе число :return: Сумма """ return a + b

Sphinx извлечёт описание и сгенерирует HTML.

Поддержка Markdown

Установи расширение:

bash
pip install myst-parser

В conf.py:

python
extensions.append("myst_parser") source_suffix = {".rst": "restructuredtext", ".md": "markdown"}

Использование тем

Установка популярной темы:

bash
pip install sphinx_rtd_theme

В conf.py:

python
html_theme = "sphinx_rtd_theme"

Полезные расширения

Расширение Назначение
sphinx.ext.autodoc Документация из docstrings.
sphinx.ext.napoleon Поддержка Google и NumPy-style docstrings.
sphinx.ext.viewcode Ссылки на исходный код.
sphinx.ext.intersphinx Межпроектные ссылки.
myst_parser Поддержка Markdown.
sphinx_copybutton Кнопка "копировать" в примерах кода.
sphinx_autodoc_typehints Типизация в документации.

Read the Docs

  1. Создай репозиторий с папкой docs/.

  2. Зарегистрируй проект на readthedocs.org.

  3. Автоматическая сборка документации при push'е на GitHub.

Пример структуры с автодокументацией

pgsql
project/ ├── mymodule/ │ └── core.py ├── docs/ │ ├── index.rst │ ├── conf.py │ └── modules.rst

В modules.rst:

rst
My Module ========= .. automodule:: mymodule.core :members:

Ког<

войти или зарегистрироваться

Мы в соцсетях