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», в рамках которого вы сможете понять готовы ли вы руководить командой системных аналитиков. Какие ключевые софт и хард скиллы вам требуются для этого.
ссылка на оригинал статьи https://habr.com/ru/articles/799687/
Добавить комментарий