Руководство по документации тестов с помощью Sphinx ==================================================== **Версия документа:** 1.0 **Дата последнего обновления:** 2025-11-27 .. contents:: Содержание :depth: 3 :local: 1 Расположение документа ------------------------- Данное руководство расположено в структуре проекта по пути: .. code-block:: text project_root/ ├── docs/ │ ├── source/ │ │ ├── conf.py │ │ ├── index.rst │ │ ├── sphinx_guide.rst <-- Этот файл │ │ └── modules.rst │ └── build/ ├── src/ │ └── your_package/ └── pyproject.toml 2 Первичная настройка для нового проекта ----------------------------------------- 2.1 Подготовка зависимостей ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash # Установка 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 ~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash # Создание структуры документации 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``: .. code-block:: python 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``: .. code-block:: rst Документация проекта ==================== .. toctree:: :maxdepth: 3 :caption: Содержание: modules Инструкции и процессы --------------------- .. toctree:: :maxdepth: 2 :caption: Документация и руководства: sphinx_guide Описание ----------- Основная документация проекта. Индексы ======= * :ref:`genindex` * :ref:`modindex` * :ref:`search` 3 Работа с существующим проектом --------------------------------- **Примечание:** Для работы с существующим проектом требуется установка Sphinx на локальной машине. 3.1 Установка зависимостей ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash # Установка Sphinx и необходимых расширений pip install sphinx sphinx-rtd-theme myst-parser # Или установка из зависимостей проекта (если настроено в pyproject.toml) pip install -e ".[docs]" 3.2 Генерация документации ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3.2.1 Базовая генерация ^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash # Генерация .rst файлов из структуры проекта sphinx-apidoc -o docs/source . -f # Сборка HTML документации sphinx-build -b html docs/source docs/build/html 3.2.2 Генерация с исключениями ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash # Исключение определенных папок из документации sphinx-apidoc -o docs/source . -f --exclude tests/ --exclude migrations/ 3.2.3 Принудительная перегенерация ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash # Принудительная перезапись существующих файлов sphinx-apidoc -o docs/source . -f --force 3.3 Очистка документации ~~~~~~~~~~~~~~~~~~~~~~~~~ Когда требуется очистка: - **После удаления модулей** - чтобы убрать ссылки на несуществующие файлы - **После переименования пакетов** - для актуализации структуры - **При изменении архитектуры проекта** - для отражения новых модулей - **При появлении предупреждений** о несуществующих модулях 3.3.1 Команды очистки ^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash # Удаление старых сгенерированных .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 Автоматизация очистки ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: makefile .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 Локальная сборка ^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash # Базовая сборка HTML sphinx-build -b html docs/source docs/build/html # Сборка с автоматическим обновлением sphinx-autobuild docs/source docs/build/html 3.4.2 Проверка качества ^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash # Проверка ссылок sphinx-build -b linkcheck docs/source docs/build/linkcheck # Проверка орфографии (требуется установка sphinxcontrib-spelling) sphinx-build -b spelling docs/source docs/build/spelling 3.4.3 Сборка для публикации ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash # Сборка 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash # Игнорирование билд-папки в Git echo "docs/_build/html/" >> .gitignore echo "docs/_build/latex/" >> .gitignore 4 Конвертация контента из MkDocs в Sphinx ------------------------------------------ 4.1 Текст ~~~~~~~~~~ **MkDocs (markdown):** .. code-block:: markdown # Заголовок Текст с **жирным** шрифтом. - Элемент списка 1 - Элемент списка 2 **Sphinx (reStructuredText):** .. code-block:: rst Заголовок ========= Текст с **жирным** шрифтом. * Элемент списка 1 * Элемент списка 2 4.2 Таблицы ~~~~~~~~~~~~ **MkDocs:** .. code-block:: markdown | Заголовок 1 | Заголовок 2 | |-------------|-------------| | Данные 1 | Данные 2 | **Sphinx:** .. code-block:: rst +-------------+-------------+ | Заголовок 1 | Заголовок 2 | +=============+=============+ | Данные 1 | Данные 2 | +-------------+-------------+ 5 Особенности Sphinx --------------------- 5.1 Поддержка docstrings ~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: python 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 Кастомные директивы ~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: rst .. 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** - домены для специфичной документации .. _version-history: История версий -------------- +---------+------------+-----------------------------------+ | Версия | Дата | Изменения | +=========+============+===================================+ | 1.0 | 2025-11-27 | Первоначальная версия руководства | +---------+------------+-----------------------------------+