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位置

Answer 1

是的你可以!

代替符号链接(在Windows上不起作用),创建一个除了.. include::指令之外什么都没有的存根文档.

我遇到了这个尝试链接到源树顶部的README文件.我将以下内容放在一个名为的文件中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的建议

Answer 2

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

来自sphinx-dev邮件列表:

在STScI,我们为Sphinx中的单个项目编写文档,然后还生成一个"主文档",其中包括(使用toctree)许多其他项目特定文档.为此,我们在主文档的doc源目录中创建符号链接到项目的doc源目录,因为toctree似乎不想包含doc源树之外的文件.

因此,不是使用shutil您复制文件,而是尝试将符号链接添加到Project/docs/spec目录中的所有模块.如果你创建了一个符号链接,Project/modules你就可以在你的toc-tree中引用这些文件modules/module1/docs/module1.

Answer 3

在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,引用同一目录中的第一个文件.所以在我的本地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: