如何在Sphinx中实现reStructuredText文件片段跨文件复用同步更新

reStructuredText原生提供了include指令，无需额外插件即可实现内容复用、修改源文件后所有引用位置自动同步的需求，具体使用方法如下：

方案1：全量引入整个rst文件内容 #

直接在目标文件需要插入内容的位置添加include指令即可，路径支持相对路径（相对于当前文件）或项目根路径（路径开头加/，相对于Sphinx配置的源文件根目录）。
示例：
在derivate.rst中插入全部base.rst的内容：

Here is some text. But the following paragraph should be the paragraph from above ^^:

.. include:: base.rst

Here the file continues.

方案2：仅引入指定文件的部分段落/章节 #

如果不需要引入整个文件，只需要引入某一段内容，可以通过start-after、end-before参数匹配源文件中的标记，仅插入标记中间的内容：

1. 首先在源文件base.rst中给需要复用的内容加上自定义标记（使用reST注释格式，不会渲染到最终页面）：

.. share_start: 公共示例段落
This is a section/paragraph I want to see in other *.rst - files.
.. share_end: 公共示例段落

2. 在目标文件derivate.rst中指定匹配的标记引入内容：

Here is some text. But the following paragraph should be the paragraph from above ^^:

.. include:: base.rst
    :start-after: .. share_start: 公共示例段落
    :end-before: .. share_end: 公共示例段落

Here the file continues.

注意事项 #

• 引入的内容会自动继承当前文件的标题层级，比如当前插入位置的上级是二级标题，引入内容中的一级标题会自动变为三级标题，符合文档结构逻辑。
• 用作公共片段的rst文件不需要加入toctree目录树，避免在全局导航中重复展示。

内容的提问来源于stack exchange，提问作者glades