python - 狮身人面像/rST : using configuration values in include statements?

Question

在我的主要 sphinx 项目中，我使用 include 语句来提取存储在我磁盘上另一个位置的文件的内容。

.. include:: //path/to/other/docs/file.rst

现在我希望能够在我的 conf.py 中设置一次基本路径，并在我的 include 语句中简单地引用它。

这可能吗？如果可能，我该如何实现？

---

供将来引用:我写了一个允许这样做的 Sphinx 扩展，请参阅: https://github.com/j0nes2k/sphinx-contrib-configurableinclude

Answer 1

你不能用 Vanilla 狮身人面像做到这一点。 include 指令的实现似乎不关心任何额外的配置选项:

• sphinx.directives.other.Include.run()
• sphinx.environment.BuildEnvironment.relfn2path()

但是您可以实现和设置自己的指令。查看Writing a simple extension节Developing extensions for Sphinx .

所以最简单的方法似乎是覆盖 sphinx.directives.other.Include。 (实际上，Sphinx 的 Include 也覆盖了标准的 include 指令 docutils.parsers.rst.directives.misc.Include 以获得更好和正确的路径解释。)