如何交叉引用内容
这是关于如何成功链接到本网站和 API 上的其他文档的入门指南。
引用内容的方法有很多，甚至太多了，对于新贡献者来说，可能很难理解要使用哪种方法。 有些方法甚至可能在本地有效，但随后却无法在部署的网站上创建功能链接。 因此，我们要求贡献者仅使用建议的 Sphinx 角色来交叉引用本网站上的内容。
学习目标
使用 Sphinx 的
:ref:和:doc:角色链接到文档和章节使用从 autosectionlabel 扩展生成的
:ref:id使用来自 doxylink 扩展的
:cpp_api:角色引用 C++ API
链接到其他文档和章节
Sphinx 提供了 :doc: 和 :ref: 角色用于`交叉引用内容 <https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#cross-referencing-using-roles>`_，最好坚持使用它们以确保与其他 Sphinx 扩展的兼容性和多发行版支持。
要链接到其他文档，您可以使用 :doc: 角色，如下所示：入门 (:doc:`/doc/tutorials/getting_started/getting_started`)。:ref: 角色接受链接到页面上明确目标的 ID。
为方便起见，我们启用了 Sphinx 扩展 autosectionlabel，它为所有部分创建唯一且人性化可读的参考目标。
可以通过提供文档路径和章节标题 like this (:ref:`like this <doc/tutorials/getting_started/getting_started:Install ROS 2 and Colcon>`) 来链接所有文档中的章节。
请注意，:doc: 角色要求绝对路径以 / 开头，而 autosectionlabel 扩展无需它即可构建 :ref 路径标签。
引用 API 文档
API 页面是使用 Doxygen 而不是 Sphinx 生成的，这意味着 :doc: 和 :ref: 角色无法找到任何 API 页面。
我们使用 doxylink 和自定义 :cpp_api: 角色从符号生成指向 API 页面的链接。
以下是一些示例，请注意，有些链接使用标题，有些则不使用：
namespaces:
:cpp_api:`moveit::core`-> moveit::coreclasses:
:cpp_api:`moveit::core::RobotModel`-> moveit::core::RobotModel职能和成员：
:cpp_api:`RobotModel::getName() <moveit::core::RobotModel::getName>`-> RobotModel::getName():cpp_api:`moveit::core::RobotModel::enforcePositionBounds(double *state) const`-> moveit::core::RobotModel::enforcePositionBounds(double *state) const:cpp_api:`RobotModel::root_link_ <moveit::core::RobotModel::root_link_>`-> RobotModel::root_link_
files:
:cpp_api:`robot_model.cpp`-> robot_model.cpp
如果您不确定如何链接某些符号，您可以在``MoveIt.tag``文件中找到所有 Doxygen 引用。
该文件位于``build/html/api/``或``build/html/<branch>/api/``内，具体取决于构建类型。
注意事项
请**做**：
尽可能多地交叉引用，尤其是代码
为链接提供有意义的标题或缩短 API 符号以提高可读性
请**不要**：
使用原始 URL 引用教程或 API
链接到 GitHub 源文件，最好使用 Doxygen 页面