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

我正在使用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

是的你可以！

代替符号链接（在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的建议

似乎答案是否定的，在toc-tree中列出的文档必须位于源目录中，即包含主文档和conf.py（以及任何子目录）的目录。

从sphinx-dev邮件列表：

在STScI，我们使用Sphinx编写各个项目的文档，然后还生成一个“主文档”，其中包括（使用toctree）许多其他这些特定于项目的文档。为此，我们在主文档的doc源目录中创建到项目的doc源目录的符号链接，因为toctree似乎实际上并不希望包含doc源树之外的文件。

因此，与其使用来复制文件，不如shutil尝试将符号链接添加到Project/docs/spec目录中的所有模块。如果您创建符号链接，Project/modules则可以像其他一样在toc树中引用这些文件modules/module1/docs/module1。

在conf.py中，使用sys.path和os.path将相对路径添加到系统

例如：

import os
import sys

sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../../Directory1'))
sys.path.insert(0, os.path.abspath('../../Directory2'))

然后照常使用index.rst，引用同一目录中的rst文件。因此，在本地Sphinx文件夹的index.rst中：

Contents:

.. toctree::
   :maxdepth: 4

   Package1 <package1.rst>
   Package2 <package2.rst>
   Package3 <package3.rst>

然后在package1.rst中，您应该能够正常引用相关的软件包。

Package1 package
=====================

Submodules
----------

Submodule1 module
----------------------------------

.. automodule:: file_within_directory_1
    :members:
    :undoc-members:
    :show-inheritance:

Submodule1 module
----------------------------------

.. automodule:: file_within_directory_2
    :members:
    :undoc-members:
    :show-inheritance:

还可以将sphinx配置为在根目录中仅包含index.rst文件，并在Project / docs中具有所有其他sphinx内容：

对于Windows，我将所有sphinx文件和目录（index.rst除外）都移到docs /中并进行了更改：

docs/make.bat：变更

set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS%  .

至

set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS%  -c . ..

docs/conf.py：添加

sys.path.insert(0, os.path.abspath('..'))

我解决了非常相似的问题，所不同的是我想包括一个外部jupyter笔记本。我已经安装了nbsphinx，但是无法正常工作。 什么没有奏效：

1. 我有想要在路径中包含根目录的目录：

   conf.py：

   import os import sys sys.path.insert(...

2. 使用该.. include:: directive文件已包含在文档中，但仍然如此。

最后解决问题的是安装软件包nbsphinx-link

一种解决方案，如果真的不可能使用相对链接进行备份，../则可以使用shutil该文件将文件复制到spec的spec文件夹树中conf.py，但是除非绝对必要，否则我不希望有多个副本。