Sphinx для автодокументирования на проекте

Sphinx был разработан 21 марта 2008 года, и является генератором документации в Python. Сам он так же был написан Python и преобразует файлы reStructuredText в HTML-вебсайты и другие форматы, включая PDF, EPub, Texinfo и man. Sphinx позволяет автоматически генерировать документацию из исходного кода, поддерживает математические записи и подсветку кода. Он используется для автоматизации создания и загрузки документации с помощью Read the Docs после каждого commit.

Установить можно через pip:

pip install -U sphinx

Про прочие системы гляньте здесь.

Начало работы и конфигурация

Для начала быстренько инициализируем проект документации в проекте (извините за тавтологию) с помощью команды sphinx-quickstart, запускаемую в корневой директории проекта. Эта команда создаст базовую структуру каталогов и файлов, необходимых для документации, также index.rst. Файл index.rst – это корневой документ документации, точка входа, которая ведет читателя по всему документационному проекту.

Sphinx спросит, хотите ли вы разделять исходные файлы и файлы сборки. Я предпочитаю использовать разделение, чтобы поддерживать чистоту проекта.

Далее будет предложено ввести название проекта и имя автора. Эти данные используются в шаблонах генерируемой документации.

Sphinx добавит некоторые папки и файлы в .gitignore, если git используется.

После инициализации нужно зайти в conf.py, который расположен в каталоге docs/source (если вы согласились на разделение директорий). Этот файл содержит все глобальные настройки проекта Sphinx:

• project и author: указанные ранее значения используются здесь для генерации метаданных документации.

• extensions: сфинкс поддерживает расширения для добавления новых возможностей. Например, sphinx.ext.autodoc для автоматической генерации документации из docstrings, sphinx.ext.viewcode для добавления ссылок на исходный код, sphinx.ext.napoleon для поддержки Google и NumPy стилей docstrings.

• templates_path и html_static_path: здесь указываются пути к каталогам с пользовательскими шаблонами и статическими файлами соответственно, что позволяет кастомизировать внешний вид вашей документации.

• html_theme: определяет тему оформления документации. Sphinx предлагает несколько встроенных тем, таких как 'alabaster', 'classic' или 'sphinx_rtd_theme', последнюю как раз чаще всего юзают

Пример

Рассмотрим пример конфигурации, который я часто использую в своих проектах, также включим несколько ключевых опций, которые на мой взгляд, важны для каждого проекта:

# conf.py

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

project = 'Великий проект'
author = 'name'
version = '0.1'
release = '0.1.0'

extensions = [
    'sphinx.ext.autodoc',  # авто документации из docstrings
    'sphinx.ext.viewcode',  # ссылки на исходный код
    'sphinx.ext.napoleon',  # поддержка Google и NumPy стиля документации
    'sphinx.ext.todo',  # поддержка TODO
    'sphinx.ext.coverage',  # проверяет покрытие документации
    'sphinx.ext.ifconfig',  # условные директивы в документации
]

html_theme = 'alabaster'  # тема оформления
html_static_path = ['_static']  # папка со статическими файлами (например, CSS)
todo_include_todos = True  # показывать TODO в готовой документации

autodoc_mock_imports = ["тяжеловесные_модули"]  # модули для мокирования

Создание и оформление документации

Организуем проект Sphinx с помощью reStructuredText (.rst).

Заголовки создаются путем подчеркивания текста символами, такими как =, -, * и так далее, с различным уровнем важности:

=================
Главный заголовок
=================

Подзаголовок
------------

Еще меньший заголовок
~~~~~~~~~~~~~~~~~~~~~

Можно создавать нумерованные и маркированные списки, используя простую разметку:

- Пункт маркированного списка
- Еще один пункт списка

1. Первый пункт нумерованного списка
2. Второй пункт списка

Ссылки позволяют связывать документацию с внешними ресурсами или другими частями документации:

`Google <https://google.com>`_

Ссылка на документ :doc:`another_document`.

Можно блоки кода с подсветкой синтаксиса, используя спец директивы:

.. code-block:: python

    def hello_world():
        print("Hello, world!")

Создание таблиц в reST может быть выполнено несколькими способами, но один из самых юзабельных — это сетка:

+---------------+---------------+
| Заголовок 1   | Заголовок 2   |
+===============+===============+
| Ячейка 1      | Ячейка 2      |
+---------------+---------------+
| Ячейка 3      | Ячейка 4      |
+---------------+---------------+

Сноски и цитаты добавляют пояснения и источники информации в текст:

.. [1] Текст сноски.

Цитата представлена таким образом.

Есть todo и tip:

.. todo:: Напоминание о том, что нужно сделать.

.. tip:: Полезный совет.

Также есть sphinx.ext.autodoc , с ним можно включать в документацию автоматически обновляемые секции кода. autodoc извлекает документацию непосредственно из docstrings.

Чтобы использовать autodoc, добавляем его в список расширений в conf.py:

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

Чтобы документировать класс или функцию используем automodule:

.. automodule:: my_module
   :members:

Тут автоматом сгенерирует документацию для всех классов и функций в модуле my_module, используя их docstrings.

Еще есть годное расширение sphinx.ext.napoleon и оно позволяет Sphinx корректно интерпретировать docstrings, написанные в стилях Google или NumPy.

Включается оно также как и все:

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

Пример docstring в стиле Google:

def function(param1, param2):
    """Summary line.

    Extended description of function.

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: Description of return value.
    """
    return True

Пример docstring в стиле NumPy:

def function(param1, param2):
    """
    Summary line.

    Extended description of function.

    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : str
        The second parameter.

    Returns
    -------
    bool
        Description of return value.
    """
    return True

Статическое содержимое

Статическое содержимое – это те файлы, которые не изменяются во время работы документации. Это CSS-стили или js-файлы, все это делает доки красивей.

Для включения статического содержимого в Sphinx, нужно поместить его в папку, указанную в переменной html_static_path в файле conf.py. Например:

html_static_path = ['_static']

Теперь, если нужно добавить изображение в документацию, помещаем его в папку _static и юзаем следующий синтаксис в вашем .rst файле:

.. image:: /_static/your-image.png
   :alt: Описание изображения

Можно интегрировать также диаграммы, сгенерированные с помощью Graphviz, напрямую в документацию. Для этого установим расширение sphinx.ext.graphviz и добавим его:

extensions = [
    'sphinx.ext.graphviz',
]

Используем директиву graphviz для создания диаграммы:

.. graphviz::

   digraph G {
      A -> B;
      B -> C;
      A -> C;
   }

Этот код создаст диаграмму, показывающую направленный граф от A к B и C.

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

После того как все настроено, пора запустить генерацию. Это делается при помощи команды sphinx-build, которая преобразует исходные файлы .rst и docstrings в финальную документацию:

sphinx-build -b html <source> <destination>

где <source> — это папка с исходными файлами Sphinx (обычно docs/source), а <destination> — папка, куда будет сгенерирована документация (например, docs/build).

По итогу генерации будет получен html файлик.

Можно юзать CI, такие как GitHub Actions или GitLab CI, процесс генерации документации можно сделать полностью автоматическим.

К примеру GitHub Actions использует YAML-файлы для описания workflow. Создаем файл .github/workflows/docs.yml в репозитории GitHub. Файл будет содержать инструкции для автоматизации генерации документации:

name: Build and Deploy Documentation

on:
  push:
    branches:
      - main  # название ветки

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 0  # необходимо для получения всей истории репозитория

    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.x'  # версия питона

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install sphinx sphinx-rtd-theme  # зависимости

    - name: Build Documentation
      run: |
        cd docs  # переход в каталог с документацией
        make html  # генерация документации

    - name: Deploy Documentation to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./docs/_build/html  # путь к сгенерированной документации

В настройках репозитория на GitHub, в разделе "Pages" и настраиваем источник GitHub Pages на ветку gh-pages.

---

В завершение хочу пригласить вас на бесплатный вебинар курса "Системный аналитик. Team Lead", в рамках которого вы сможете понять готовы ли вы руководить командой системных аналитиков. Какие ключевые софт и хард скиллы вам требуются для этого.

• Зарегистрироваться на бесплатный вебинар