[ru] Создание документации при помощи sphinx и doxygen

2018-02-23

Categories: notes Tags: Other documentation sphinx

Введение

Описана схема настройки автоматической генерации документации для проекта, написанного на Python и C. В качестве основного бэкенда для документации используется Sphinx. Парсинг докстрингов из C-кода осуществляется при помощи Doxygen, с дальнейшей интеграцией в Sphinx при помощи модуля breathe.

Общая архитектура создаваемой документации выглядит следующим образом:

Установка

Сначала потребуется установить необходимые пакеты. Для Debian Stretch это:

apt-get install doxygen python-breathe python-sphinx

Подготовка проекта

При помощи скрипта sphinx-quickstart инициализировать Sphinx в директории с исходниками проекта:

mkdir -v doc
cd doc
sphinx-quickstart

В результате выполнения sphinx-quickstart будет создана следующая структура файлов:

_build  conf.py  index.rst  make.bat  Makefile  _static  _templates

Создадим директорию doxygen, в которой инициализируем Doxygen:

mkdir -v doxygen
doxygen -g
cd doxygen

Будет создан Doxyfile с дефолтным содержанием. Потребуется отредактировать следующие строки:

OUTPUT_DIRECTORY = ./doxygen
INPUT = ../path-to-c-sources-in-project
GENERATE_HTML = NO
GENERATE_LATEX = NO
GENERATE_XML  = YES

В данном случае мы подключаем вывод в формате XML, который будет использован breathe при конвертации в Sphinx и указываем пути до входных и выходных файлов, которые используем далее в Makefile Sphinx.

Добавить в conf.py модуль breathe и создадим тестовый проект test_target, к которому обратимся далее в .rst документации:

import breathe
# ...
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'breathe']
# ...
# -- Breathe: Integration with C via Doxygen -----------------------------------
breathe_projects = { "test_target": "./doxygen/xml/" }
breathe_default_project = "test_target"

Создадим в Makefile Sphinx правила для сборки документации Doxygen:

DOXYDIR     = ./doxygen
# ...
doxy:
  doxygen $(DOXYDIR)/Doxyfile
  @echo
  @echo "Doxygen routine for targets finished."
# ...
html: doxy
  $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
  @echo
  @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
# ...

Создать .rst файлы, в которых указаны выходные файлы Doxygen:

cat <<EOT >> test.rst
.. doxygenfile:: test.c
   :project: test_target
EOT

Запустить билд:

make html

Результат можно увидеть в указанной в Makefile output-директории:

Ссылки