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

我试图在主文档目录树中包含如下文件：

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

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

但是，此错误消息会导致：

WARNING: toctree contains reference to nonexisting document u'modules/module1/docs/module1'

不可能在文档路径中使用../吗？

更新：添加conf.py位置

更新： 除了下面的包含技巧，这仍然是不可能的（2019年）。有一个悬而未决的问题一直在推进：https://github.com/sphinx-doc/sphinx/issues/701

Answer 1

是的，你可以！

代替symlink（它在Windows上不起作用），创建一个存根文档，该文档中除了.. include::指令之外什么都没有。

我试图链接到源代码树顶部的自述文件时遇到了这个问题。我在一个名为readme_link.rst的文件中放入了以下内容：

.. include:: ../README

然后在index.rst中，我使目录树看起来像：

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

现在我在我的索引页上有一个到我的发行说明的链接。

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