sphinx可以链接到不在根文档下的目录中的文档吗？

Question

我正在使用Sphinx记录非Python项目。我想./doc在每个子模块中分发文件夹，其中包含submodule_name.rst用于记录该模块文件的文件。然后，我想将这些文件吸收到主层次结构中，以创建整个设计的规范。

即：

Project
  docs
    spec
      project_spec.rst
      conf.py
  modules
    module1
      docs
        module1.rst
      src
    module2
      docs
        module2.rst
      src

我试图project_spec.rst像这样在主文档toctree中包含文件：

.. toctree::
   :numbered:
   :maxdepth: 2

   Module 1 <../../modules/module1/docs/module1>

但是，此错误消息导致：

警告：toctree包含对不存在的文档u’modules / module1 / docs / module1’的引用

是否无法以../某种方式在文档路径中使用？

更新：添加了conf.py位置

更新：除了下面的包含技巧之外，仍然不可能（2019）。有一个开放的问题正在不断推进：https : //github.com/sphinx-
doc/sphinx/issues/701

Answer 1

是的你可以！

代替符号链接（在Windows上不起作用），创建一个存根文档，该文档中除了.. include::指令外什么也没有。

我遇到了这种情况，试图链接到源树顶部的自述文件。我将以下内容放在名为的文件中readme_link.rst：

.. include:: ../README

然后在中index.rst，我使toctree看起来像：

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

现在，我在索引页面上有指向发行说明的链接。

感谢http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-
sphinx.html
的建议