# Руководство по документации тестов с помощью 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 | Первоначальная версия руководства