Автоматическое обновление документации Doxygen и обеспечение ее доступности для пользователей с CMake - PullRequest
0 голосов
/ 21 февраля 2019

Я работал над несколькими библиотеками C ++, которые созданы на основе CMake и запускают Doxygen для генерации HTML-документации.В каждой из этих библиотек документация встроена в папку «html» в каталоге «build» CMake и никогда не просматривается никем.

Потому что, честно говоря, большинство людей не делаютвообще не люблю читать документацию - не говоря уже о ее поиске.

Это приводит к нескольким вопросам:

  1. Существует ли стандартное место для установкидокументация, как только она будет собрана, где пользователям будет очень ясно, что документация доступна для библиотеки?

  2. Как я могу гарантировать, что каждый раз, когда моя библиотека собирается, документация будет автоматически обновляется и устанавливается в этом стандартном месте?

  3. Существует ли какой-либо стандартный способ сохранить прошлые версии документации для справки на случай, если кто-то использует более раннюю версию библиотеки?

Ответы [ 2 ]

0 голосов
/ 22 февраля 2019

У вас, кажется, есть две очень разные проблемы:

A.Разработчики, создающие программное обеспечение, даже не знают о той части сборки, которую они используют

B.Обычные пользователи не знают, есть ли доступная документация (от doxygen или еще)

B.это не совсем технический вопрос, поэтому я сосредоточусь на разработчиках.Во-первых, вы должны сделать doxygen частью сборки "я отказался", я имею в виду, включен по умолчанию.Просто используйте для этого обычную (и фальшивую) зависимость cmake;другими словами, лгите cmake и притворяйтесь, что для сборки библиотеки требуется doxygen.В правиле / команде doxygen используйте функцию COMMENT cmake со следующим: COMMENT "документирование сборки doxygen в $ {DOXYOUT}".Как обычно, разработчики заметят это.В самом конце сборки используйте сообщение cmake «Напоминание, вы только что собрали документацию в $ {DOXYOUT}»

Теперь вернемся к более конкретным вопросам:

  1. Нет стандартного местоположенияно см. выше вместо этого.
  2. См. выше.
  3. Используйте обычный репозиторий контроля версий и проверяйте папки вывода doxygen каждый раз, когда вы делаете релиз.Это может быть частью вашей автоматизации выпуска.

Также взгляните на https://readthedocs.org/

0 голосов
/ 22 февраля 2019

1) Согласно стандарту Иерархия файловых систем

4.11.3.Определенные параметры
Следующие каталоги или символические ссылки на каталоги должны быть в / usr / share, если установлена ​​соответствующая подсистема:
Описание каталога
...
doc Разная документация (необязательно)

2) Я бы сказал, вы можете добавить к цели установки команду для копирования doxygen в префикс / usr / share / doc

Кроме того, сначала в директории сборки также есть doxygen, кажется нормальным ИМХО.

3) Обычно с дистрибутивом есть менеджер пакетов, который выможет создать пакет документов, поэтому пользователю, который хочет, чтобы «предыдущий» документ просто нуждался в получении документа пакета с той же ревизией, что и в двоичном пакете ...

примечание: в Archlinux документ поставляется вместе с библиотекой, в Debianкак у вас есть package-doc, то же самое для homebrew IIRC

примечание: вы также можете настроить doxygen, чтобы сгенерированное сообщение об ошибке могло быть проанализировано вашим ide (например, QtCreator), как обычная ошибка gcc, чтобы вы могли увидеть их вжурнал ошибок на каждой сборке.

...