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

Question

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

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

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

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

Answer 1

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

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

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

http://www.sphinx -doc.org / ru / master / use / extensions / intersphinx.html

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

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

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

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

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

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

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

pip install sphinxcontrib-moderncmakedomain

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