Руководство по документации тестов с помощью Sphinx

Версия документа: 1.0 Дата последнего обновления: 2025-11-27

1 Расположение документа 

Данное руководство расположено в структуре проекта по пути:

project_root/
├── docs/
│   ├── source/
│   │   ├── conf.py
│   │   ├── index.rst
│   │   ├── sphinx_guide.rst  <-- Этот файл
│   │   └── modules.rst
│   └── build/
├── src/
│   └── your_package/
└── pyproject.toml

2 Первичная настройка для нового проекта 

2.1 Подготовка зависимостей 

# Установка Sphinx и тем
pip install sphinx sphinx-rtd-theme myst-parser

# Добавление в pyproject.toml
echo [project.optional-dependencies] >> pyproject.toml
echo docs = [ >> pyproject.toml
echo "sphinx>=8.2.3", >> pyproject.toml
echo "sphinx-rtd-theme>=2.0.0", >> pyproject.toml
echo "myst-parser>=2.0.0" >> pyproject.toml
echo ] >> pyproject.toml

2.2 Инициализация Sphinx 

# Создание структуры документации
sphinx-quickstart docs --sep -p "PROJECT_NAME" -a "TEAM_NAME" -l ru --ext-autodoc --ext-viewcode --makefile --no-batchfile

2.3 Настройка конфигурации 

Обновите docs/source/conf.py:

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

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

autodoc_default_options = {
    'members': True,
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

autodoc_typehints = 'description'
napoleon_google_docstring = True
napoleon_numpy_docstring = False
html_theme = 'sphinx_rtd_theme'

2.4 Настройка главной страницы 

Обновите docs/source/index.rst:

Документация проекта
====================

.. toctree::
   :maxdepth: 3
   :caption: Содержание:

   modules

Инструкции и процессы
---------------------

.. toctree::
   :maxdepth: 2
   :caption: Документация и руководства:

   sphinx_guide

Описание
-----------
Основная документация проекта.

Индексы
=======

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

3 Работа с существующим проектом 

Примечание: Для работы с существующим проектом требуется установка Sphinx на локальной машине.

3.1 Установка зависимостей 

# Установка Sphinx и необходимых расширений
pip install sphinx sphinx-rtd-theme myst-parser

# Или установка из зависимостей проекта (если настроено в pyproject.toml)
pip install -e ".[docs]"

3.2 Генерация документации 

3.2.1 Базовая генерация 

# Генерация .rst файлов из структуры проекта
sphinx-apidoc -o docs/source . -f

# Сборка HTML документации
sphinx-build -b html docs/source docs/build/html

3.2.2 Генерация с исключениями 

# Исключение определенных папок из документации
sphinx-apidoc -o docs/source . -f --exclude tests/ --exclude migrations/

3.2.3 Принудительная перегенерация 

# Принудительная перезапись существующих файлов
sphinx-apidoc -o docs/source . -f --force

3.3 Очистка документации 

Когда требуется очистка:

После удаления модулей - чтобы убрать ссылки на несуществующие файлы
После переименования пакетов - для актуализации структуры
При изменении архитектуры проекта - для отражения новых модулей
При появлении предупреждений о несуществующих модулях

3.3.1 Команды очистки 

# Удаление старых сгенерированных .rst файлов кроме основных
rm docs/source/modules.rst
rm docs/source/pages.rst
rm docs/source/components.rst

# Удаление всех .rst файлов кроме основных (Linux/Mac)
find docs/source -name "*.rst" ! -name "index.rst" ! -name "sphinx_guide.rst" -delete

# Удаление всех .rst файлов кроме основных (Windows PowerShell)
Get-ChildItem docs/source -Filter "*.rst" | Where-Object { $_.Name -notin @("index.rst", "sphinx_guide.rst") } | Remove-Item

3.3.2 Автоматизация очистки 

.PHONY: clean-docs rebuild-docs

clean-docs:
    rm -rf docs/build/
    find docs/source -name "*.rst" ! -name "index.rst" ! -name "sphinx_guide.rst" -delete

rebuild-docs: clean-docs
    sphinx-apidoc -o docs/source . -f
    sphinx-build -b html docs/source docs/build/html

3.4 Сборка и деплой 

3.4.1 Локальная сборка 

# Базовая сборка HTML
sphinx-build -b html docs/source docs/build/html

# Сборка с автоматическим обновлением
sphinx-autobuild docs/source docs/build/html

3.4.2 Проверка качества 

# Проверка ссылок
sphinx-build -b linkcheck docs/source docs/build/linkcheck

# Проверка орфографии (требуется установка sphinxcontrib-spelling)
sphinx-build -b spelling docs/source docs/build/spelling

3.4.3 Сборка для публикации 

# Сборка PDF (требуется LaTeX)
sphinx-build -b latex docs/source docs/build/latex

# Сборка EPUB
sphinx-build -b epub docs/source docs/build/epub

3.4.4 Настройка для CI/CD 

# Игнорирование билд-папки в Git
echo "docs/_build/html/" >> .gitignore
echo "docs/_build/latex/" >> .gitignore

4 Конвертация контента из MkDocs в Sphinx 

4.1 Текст 

MkDocs (markdown):

# Заголовок
Текст с **жирным** шрифтом.
- Элемент списка 1
- Элемент списка 2

Sphinx (reStructuredText):

Заголовок
=========
Текст с **жирным** шрифтом.
* Элемент списка 1
* Элемент списка 2

4.2 Таблицы 

MkDocs:

| Заголовок 1 | Заголовок 2 |
|-------------|-------------|
| Данные 1    | Данные 2    |

Sphinx:

+-------------+-------------+
| Заголовок 1 | Заголовок 2 |
+=============+=============+
| Данные 1    | Данные 2    |
+-------------+-------------+

5 Особенности Sphinx 

5.1 Поддержка docstrings 

def my_function(param1: str, param2: int) -> bool:
    """
    Краткое описание функции.

    Args:
        param1: Описание параметра 1
        param2: Описание параметра 2

    Returns:
        bool: Описание возвращаемого значения

    Example:
        >>> my_function("test", 5)
        True
    """
    return True

5.2 Кастомные директивы 

.. note::
   Это важное примечание.

.. warning::
   Это предупреждение.

.. code-block:: python

   def example():
       print("Hello Sphinx!")

6 Решение проблем 

6.1 Проблема: Модули не находятся 

Решение: Проверьте sys.path в conf.py

6.2 Проблема: Не генерируются docstrings 

Решение: Убедитесь, что установлены расширения autodoc и napoleon

6.3 Проблема: Тема не применяется 

Решение: Проверьте html_theme в conf.py

7 Дополнительные возможности 

Autosummary - автоматические summary таблицы
Intersphinx - ссылки между проектами
Custom domains - домены для специфичной документации

История версий 

Версия	Дата	Изменения
1.0	2025-11-27	Первоначальная версия руководства