Как правильно документировать модуль CMake?

Question

Быстрый поиск в Google (... на самом деле многие довольно обширные поиски в Google) не смогли объяснить, как правильно документировать модуль CMake.

То, что я ищу, - это способ документировать собственные модули CMake, чтобы они работали с cmake --help-module <module_name> команда. Есть ли стандартный способ сделать это? Кто-нибудь может указать мне несколько хороших примеров? Процесс документации кажется странным.... не очень хорошо задокументирован. Ха-ха.

Как работают модули, которые работают с cmake --help-module документально?

Любая помощь приветствуется.

Answer 1

Цитата из электронного письма, полученного от Брэда Кинга (члена списка рассылки разработчиков CMake):

Нет способа сделать это. Единственная причина, по которой --help-module существует, заключается в том, что до версии 3.0 документация генерировалась самим двоичным файлом CMake, и люди привыкли к доступной опции. Это только для встроенных модулей и доступно только по старым причинам, и однажды может уйти в пользу man-страниц и html-документов.

Онлайн-документы, такие как https://cmake.org/cmake/help/v3.14, публикуют /objects.inv поддерживать интерфинкс:

http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

Это было сделано по запросу некоторых пользователей, поэтому я не изучал, как это работает, но нужно иметь возможность использовать sphinx для создания собственной документации и при этом ссылаться на онлайн-документы CMake.

Если вам это удастся, мы бы приветствовали MR, чтобы добавить документы, описывающие, как, возможно, в

https://gitlab.kitware.com/cmake/cmake/blob/master/Help/dev/documentation.rst

Похоже, использование Sphinx - это путь.

Дополнительная информация:

Как Сфинкс узнает, что нужно проанализировать этот файл.cmake? Сфинкс распознает ключевое слово "cmake-module" особым образом и знает, что с ним делать?

это из модуля Sphinx, который вы можете найти в исходных кодах CMake Utilities/Sphinx/cmake.py. Или вы можете установить этот файл, используя pip:

pip install sphinxcontrib-moderncmakedomain

При настройке Sphinx необходимо указать имена расширений для использования в файле конфигурации Sphinx (conf.py) и добавить имя расширения (sphinxcontrib.moderncmakedomain) в массив расширений.

Answer 2

Хорошие новости: вы можете использовать sphinx для документирования своих модулей CMake и в то же время использовать Doxygen для документирования исходного кода C++ (или другого).

Я создал пример проекта, который показывает, как использовать в сочетании со Sphinx и Doxygen для создания документации для вашего кода C++ И кода CMake:

https://gitlab.com/Pro1/doxygen-cmake-sphinx

Он использует sphinxcontrib-moderncmakedomainпакет и сам CMake для настройки сфинкса conf.pyа затем запустите сфинкс.

Пример в значительной степени основан на официальной документации CMake из: https://gitlab.kitware.com/cmake/cmake/-/tree/master/Utilities/Sphinx .