适用于现代CMake的Sphinx域

以下内容直接来自Kitware git仓库的Utilities目录。原始的sphinxcontrib-cmakedomain已经很久没有更新，因此它已经非常过时。在没有这个工具的情况下，在项目中记录CMake域实体是非常痛苦的。这个工具的工作方式与Kitware完全相同，因此可能需要一些时间来研究他们解决这些问题的方法。

此存储库的许可证与CMake的所有许可证相同，即BSD-3-Clause许可证。

🚨🚨🚨使用此插件遇到任何问题都必须报告给Kitware，除非它们涉及包装本身。Python文件与发布版本的CMake源代码完全匹配。🚨🚨🚨

安装

PyPI

此域可通过PyPI获取。您可以通过pip直接安装它

$ pip install sphinxcontrib-moderncmakedomain

或者，将其放在您的setup.py、pyproject.toml、requirements.txt或您用于声明和管理依赖项的任何系统中。通常只有当CMake中的此扩展发生变化时，才会发布新版本。

Git

此模块也可以通过pip和GitHub直接安装

$ pip install git+https://github.com/scikit-build/moderncmakedomain.git

用法

要启用moderncmakedomain的使用，请将sphinxcontrib.moderncmakedomain添加到您的conf.py文件中的extensions变量

extensions = [..., 'sphinxcontrib.moderncmakedomain', ...]

该插件目前提供了一些指令和引用。以下将进行说明。

指令

要声明以下任何引用，它们必须放置在sphinx SOURCEDIR/master doc下与同一名称的目录中。因此，prop_tgt/MY_PERSONAL_PROPERTY.rst可以通过:prop_tgt:`MY_PERSONAL_PROPERTY`进行引用。这是CMake目前允许声明新属性的唯一方式。

引用

以下每个引用都可以放置在与同一名称的目录中以记录您CMake库提供的自定义扩展。

历史

sphinx-moderncmakedomain最初由slurps-mad-rips于2018年10月开发，旨在通过简单地发布一个相同的Python包来帮助编写CMake文档。这是简化基于sphinx的文档维护并避免系统性地复制CMake仓库中维护的关联Python模块的一个关键步骤。

2021年8月初，henryiii在处理scikit-build issue #574 时发现了 sphinx-moderncmakedomain 项目，旨在简化文档生成基础设施并避免更新sphinx扩展的本地副本。henryiii 和 jcfr 与 slurps-mad-rips 合作，制定了一个过渡计划，在scikit-build组织内共同维护该项目。