Цель и необходимость
Для
меня документация всегда была важным пунктом на этапе оценки проекта и
передачи знаний третьим лицам. Хотелось бы максимально упростить
процесс, особенно прорисовку диаграмм.
Какие начальные требования:
- Docs as code или генерация документации из кода, в том числе диаграмм.
- Удобный поиск и навигация.
- Простота генерации документации.
Для себя выбрал Sphinx в связке с PlantUML..
Установка
Я использую ядро Linux, поэтому все команды будут в данной OS.
Установка java
Проверяем установку java:
java --version
Если java установлена, то не выполняем последующие действия.
Ищем доступные версии для установки (Arch Linux): sudo pacman -sS java | grep jdk. Устанавливаем java:
sudo pacman -S jdk-openjdk
Версию проверяем командой выше.
Установка PlantUML
Идем по адресу https://plantuml.com/ru/download и качаем исходный код PlantUML.:
wget -O ~/.java/plantuml.jar https://github.com/plantuml/plantuml/releases/download/v1.2025.2/plantuml-1.2025.2.jar
Проверка работы командой: java -jar ~/.java/plantuml.jar
Установка Sphinx
Создаем виртуальное окружение:
# Создаем виртуальное окружение
python -m venv .venv
# Активируем виртуальное окружение
source .venv/bin/activate
Актуальные библиотеки можно найти в этом файле requirements.txt
Sphinx>=8.2.3
sphinx-markdown-builder>=0.6.8
sphinx-togglebutton>=0.3.2
sphinx-rtd-theme>=3.0.2
myst-parser>=4.0.1
sphinx-markdown-tables>=0.0.17
sphinxcontrib-plantuml>=0.30
Установить можно командой: pip install -r requirements.txt
Сборка документации
Для документации создадим отдельную директорию: mkdir docs
Первый запуск:
sphinx-quickstart docs
После первого запуска должна быть похожая структура директорий:
./docs
├── _build
├── _images
│ └── 100x100
├── _plantuml
│ └── da
├── source
│ └── plantuml
├── _sources
├── _static
│ ├── css
│ │ └── fonts
│ ├── fonts
│ │ ├── Lato
│ │ └── RobotoSlab
│ └── js
└── _templates
В директории source должны хранится все исходники кода.
Как может выглядеть conf.py:
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'server'
copyright = '2025, Volokzhanin Vadim'
author = 'Volokzhanin Vadim'
release = '0.0.1'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
'sphinx.ext.intersphinx',
'sphinxcontrib.plantuml',
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx_markdown_builder',
'sphinx.ext.napoleon',
'sphinx.ext.autosectionlabel',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
'sphinx_togglebutton',
'myst_parser'
]
templates_path = ['_templates']
exclude_patterns = [
'build/*'
]
plantuml = ['java', '-jar', '/home/volokzhanin/.java/plantuml.jar']
language = 'ru'
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_sidebars = {
'**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
'using/windows': ['windowssidebar.html', 'searchbox.html'],
}
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
markdown_uri_doc_suffix = ".html"
pygments_style = 'sphinx'
source_suffix = ['.rst', '.md']
myst_heading_anchors = 4
Run
Возможный состав index.rst:
.. server documentation master file, created by
sphinx-quickstart on Thu Apr 17 19:27:04 2025.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Добро пожаловать в репозиторий cервера Волокжанина Вадима!
====================================
.. toctree::
:maxdepth: 4
:caption: Содержимое:
main.md
Сборка документации после изменений:
sphinx-build -b html docs/source/ docs
После
сборки у нас появляются диаграммы вставленные в наши файлы и картинки
автоматически генерируются на основе кода. Возможности у Sphinx очень
широкие и этот проект для своей документации выбрали: Bazaar, SQLAlchemy, MayaVi, SageMath, SciPy, Django и Pylons.
Настройка VSCode
В своей работе использую как IDE Visual Studio Code. Для эффективной работы с документацией необходимо установить несколько расширений:
- PlantUML - позволяет через горячие клавиши (Alt + D) отображать PlantUML диаграммы.
- Open In Default Browser - позволяет в Вашем браузере по умолчанию открывать *.html файлы до отправки в git.
Настройка github
Пример кода документации через sphinx.
В GitHub репозитории переходим: Settings->Pages-><path>. Где path - ветка и папка откуда будет извлекаться документация. В результате получаем бесплатное публичное место для хостинга своей документации, например.
Итог
В результате получаем:
- Улучшение сотрудничества.
Документация напрямую интегрируется в процесс разработки программного
обеспечения, что способствует активному участию всей команды в создании и
обзоре документов. - Контроль версий.
Отслеживание и управление изменениями в документации вместе с
модификациями кода. Это снижает риски устаревшей или противоречивой
информации. - Автоматизация публикации.
Оптимизируется процесс генерации и развертывания документации.
Автоматизация существенно уменьшает ручной труд и количество ошибок,
обеспечивает быстрое и точное отражение последних обновлений. - Гарантия качества.
Каждое изменение или обновление документации может проходит строгие
тесты на точность и актуальность. Это повышает качество и надёжность
материалов. - Доступность документации.
Документация хранится в репозиториях вместе с кодом, что позволяет
разработчикам легко получать доступ к актуальной информации. - Гибкость.
Документация легко обновляется и настраивается по мере необходимости.
Это важно для прогрессивных проектов, где необходимы быстрые и точные
отражения изменений в документах. - Сокращение временных затрат. Публикация с помощью Docs as Code может быть сведена к выполнению одной команды или даже полностью автоматизирована.
*.wikipedia.org - РКН: иностранный владелец ресурса нарушает закон РФ