是否可以在我的文档中包含外部 rst 文件？答案

【问题标题】：Is it possible to include external rst files in my documentation?是否可以在我的文档中包含外部 rst 文件？
【发布时间】：2021-03-05 15:24:35
【问题描述】：

我正在为包含模块的平台构建文档。我想让文档存在于这些模块存储库中，并使用 include 命令将它们包含在“主”文档中。

我尝试了以下方法：

.. include:: https://github.com/12rambau/sepal_ui_template/blob/master/doc/en.rst

但文件中没有添加任何内容

includecommand 中是否可以使用绝对链接？

【问题讨论】：

因为它可能是安全黑洞，我怀疑该指令是否接受这样的 URL。

标签： python-sphinx read-the-docs

【解决方案1】：

没有。完全限定的 URL 与文档无关。根据include directive 的文档：

指令参数是要包含的文件的路径，相对于包含指令的文档。

还有其他选择，包括this one。

【讨论】：

【解决方案2】：

我的主要目标不是使用include 命令，而是避免代码重复并使用网络上提供的文件。基于@Steve piercy 的回答我想出了这个解决方案：

在conf.py 文件中，我从 github 复制文件的内容

小心使用raw.githubusercontent.com链接避免导入html


# [...]
# -- Copy the modules documentation ------------------------------------------

from urllib.request import urlretrieve

urlretrieve (
    "https://raw.githubusercontent.com/12rambau/sepal_ui_template/master/doc/en.rst",
    "modules/sepal_ui_template.rst"
)

之后，该文件在我的文档中的modules/sepal_ui_template.rst 下创建，我可以安全地访问它。

每次我重建我的文档时都会重新下载。

【讨论】：