Sphinx для автодокументирования на проекте14.03.2024 12:00
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 `_
Ссылка на документ :doc:`another_document`.
Можно блоки кода с подсветкой синтаксиса, используя спец директивы:
Сноски и цитаты добавляют пояснения и источники информации в текст:
.. [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
где — это папка с исходными файлами Sphinx (обычно docs/source), а — папка, куда будет сгенерирована документация (например, 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», в рамках которого вы сможете понять готовы ли вы руководить командой системных аналитиков. Какие ключевые софт и хард скиллы вам требуются для этого.
