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

似乎答案是否定的，toc树中列出的文档必须位于source directory目录中，即包含master document和conf.py的目录（以及任何子目录）。

从sphinx-dev mailing list：

At STScI, we write documentation for individual projects in Sphinx, and then also produce a "master document" that includes (using toctree) a number of these other project-specific documents. To do this, we create symlinks in the master document's doc source directory to the projects' doc source directories, since toctree really doesn't seem to want to include files outside of the doc source tree.

因此，与其使用shutil复制文件，不如尝试向Project/docs/spec目录中的所有模块添加符号链接。如果您创建指向Project/modules的符号链接，那么您将在toc树中引用这些文件，简单地称为modules/module1/docs/module1等

Answer 2

在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文件。所以在我的index.rst本地Sphinx文件夹中：

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:

Answer 3

是的，你可以！

代替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的建议