использование Doxygen в документации для чтения

Я написал документацию для программного обеспечения C++ среднего размера, используя Doxygen вместе с Markdown. Я вполне доволен этим, так как после изменения слоя xml я получил что-то вроде этого: http://docs.mitk.org/nightly/index.html

Я хотел бы разместить эту документацию в Интернете, в идеале с помощью чего-то вроде ReadtheDocs, где документация будет автоматически создаваться после «git commit» и размещаться для просмотра.

ReadtheDocs выглядит как идеальный сайт, но использует Sphinx и reStructuredText по умолчанию. Doxygen тоже можно использовать, но, насколько я знаю, только через Breathe. Прохождение по этому маршруту, по сути, означает, что мне нужно будет реструктурировать всю документацию, если я не хочу выгружать всю документацию по API на одну страницу (http://librelist.com/browser//breath/2011/8/6/fwd-guidance-for-usage-breathe-with-existing-doxygen-set-up-on-a-large-project/#cab3f36b1e4bb2294e2507acad71775f).

Как это ни парадоксально, Doxygen установлен на сервере для чтения документов, но после борьбы я не смог найти обходной путь, чтобы пропустить его Sphinx или Mkdocs.


read-the-docs doxygen
person solernou    schedule 17.03.2016    source источник

Ответы (1)


arrow_upward
14
arrow_downward

Я попробовал следующее решение для использования Doxygen в Read The Docs, и, похоже, оно работает:

  1. настроить пустой проект sphinx (см. официальную документацию sphinx),
  2. в sphinx conf.py добавьте команду для сборки документации doxygen,
  3. используйте директиву конфигурации conf.py html_extra_path, чтобы перезаписать сгенерированную документацию doxygen поверх сгенерированной документации sphinx.

Я тестировал это со следующим исходным деревом:

.../doc/Doxyfile
       /build/html
       /sphinx/conf.py
       /sphinx/index.rst
       /sphinx/...

Некоторое объяснение:

  1. в моей настройке doxygen создает свою документацию в «doc/build/html»,
  2. ReadTheDocs запускает свои команды в каталоге, где находится файл conf.py.

Что делать:

  1. добавьте следующие строки в conf.py для создания документов doxygen:

     import subprocess
 subprocess.call('cd .. ; doxygen', shell=True)

  2. обновить директиву conf.py html_extra_path на:

     html_extra_path = ['../build/html']

В этой конфигурации ReadTheDocs должен правильно генерировать и хранить HTML-документацию Doxygen.

сделать:

  • другие форматы документации, например: pdf.
person kzeslaf    schedule 17.12.2016
comment
Да, это сработало как шарм, большое спасибо. С другой стороны, я использую CMake для настройки ряда файлов, и было бы неплохо, если бы он был установлен на сервере readthedocs. На данный момент я перекодировал эту конфигурацию в conf.py, хотя было бы здорово иметь CMake, чтобы не поддерживать две части программного обеспечения, делающие одно и то же. - person solernou; 10.06.2017
comment
Описанный выше метод также задокументирован здесь: breathe.readthedocs.io/en/latest/readthedocs. html - person TimSC; 03.12.2017
comment
обязательно ознакомьтесь с этим сообщением в блоге devblogs.microsoft.com/cppblog/ - person Cfir TSabari; 05.10.2019
comment
Отличный ответ. Бит html_extra_path для копирования документа Doxygen поверх документа Sphinx, чтобы он работал на сайте Readthedocs, — это... счастливое волшебство! - person James Leedham; 19.05.2021