e-nms_qa_automation/docs/source/sphinx_guide.rst

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