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

【问题标题】：Can sphinx link to documents that are not located in directories below the root document?sphinx 可以链接到不在根文档下的目录中的文档吗？
【发布时间】：2012-04-29 06:21:36
【问题描述】：

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

【问题讨论】：

是否需要将.rst 扩展名添加到Module 1 <../../modules/module1/docs/module1> 行？
我不这么认为，因为在Sphinx Docs：由于reST源文件可以有不同的扩展名（有些人喜欢.txt，有些人喜欢.rst——扩展名可以用source_suffix配置）并且不同的操作系统有不同的路径分隔符，Sphinx 对它们进行了抽象：所有“文档名称”都相对于源目录，扩展名被剥离，路径分隔符被转换为斜杠。
好吧，只是猜测！所以我假设source_suffix 在您的conf.py 配置文件中设置为.rst。另外，这个文件在你的目录层次结构中的什么位置，因为似乎所有的路径都是相对于这个文件的？
是的，source_suffix 设置为 .rst，conf.py 与 project_spec.rst 文件位于同一文件夹中。

标签： python python-sphinx symlink toctree

【解决方案1】：

是的，你可以！

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

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

【讨论】：

如果自述文件中的图像或类似文件的相对路径在 index.rst 所在的目录中无效，您如何处理？我收到“图像文件不可读”错误。
我刚刚回到这里并接受了这个答案，谢谢！不确定图片，但您可以随时将它们复制到 conf.py 中。
我需要使用.. include:: ../readme.rst，包括扩展名。
仅包含部分 README.rst：muffinresearch.co.uk/…
我得到了“没有标题”，如 stackoverflow.com/questions/14079655/… 中所述；所以我不得不在 include 指令上方添加一个标题（并从指向的 README.rst 中删除相同的标题，以避免冗余）

【解决方案2】：

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

来自sphinx-dev mailing list：

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

因此，您可以尝试将符号链接添加到 Project/docs/spec 目录中的所有模块，而不是使用 shutil 复制文件。如果您创建指向Project/modules 的符号链接，那么您将在您的目录树中引用这些文件，就像modules/module1/docs/module1 等一样。

【讨论】：

那太糟糕了。我在尝试从 Word 文档切换到 Sphinx 时看到的优势之一是，您可以将可重用的硬件模块导入您的项目，并将其文档包含在设计的主文档中。我会使用符号链接，但可惜我在 Windows 上。
为了后代，我尝试将子模块 doc 文件夹添加到 conf.py 中的sys.path，但这没有用。
@mc_electron 对于 Windows 上的符号链接，使用 mklink 命令。

【解决方案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，引用同一目录中的 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:

【讨论】：

这是新行为吗？它是在哪个版本中添加的？
如果进一步描述以告知初学者会很棒。例如，Package1 是什么？是使用sys.path.insert 指定的第一个path 吗？或者，在某个地方有教程吗？我似乎找不到相关文档。
Package1 是一个命名条目，因此 TOC 将“Package1”显示为该部分的标题。
这允许你在另一个目录中自动生成 Python 模块，但它不允许你在另一个目录中包含 RST 文件。

【解决方案4】：

我解决了我非常相似的问题，但我想包含一个外部 jupyter 笔记本。我已经安装了 nbsphinx，但我无法让它工作。 什么不起作用：

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

conf.py：

import os import sys sys.path.insert(...
使用.. include:: directive，该文件已包含在文档中，但原样。

最后解决了问题是安装包nbsphinx-link

【讨论】：

【解决方案5】：

也可以将 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('..'))

【讨论】：

谢谢！当我在一个存储库中有多个相关包时，该配置对我来说效果很好，引用自同一个文档。

【解决方案6】：

另一种不需要创建存根文件的技术是在您的目录树根中使用absolute references（以/ 开头），并在调用sphinx-build 时将源目录设置为最低的共同祖先。示例目录布局：

/path/to/common/ancestor
├── a
│   └── foo.rst
├── b
│   ├── bar.rst
│   ├── x
│   │   └── index.rst
│   └── y
│       └── boz.rst
└── c
    └── baz.rst

还有b/x/index.rst：

.. toctree::
   /a/foo
   /b/bar
   /b/y/boz
   /c/baz

您的sphinx-build 命令可能如下所示：

sphinx-build -c <confdir> -b html -D masterdoc=b/x/index /path/to/common/ancestor <outdir>

我用 sphinx 3.0.2 对此进行了测试。

【讨论】：

这种技术的一个缺点是输出目录中的主输出文档不是./index.html，而是./b/x/index.html。

【解决方案7】：

我的回答本质上是@Dan Menes，但对于 Myst 解析器而不是 reStructured。

我更愿意将此作为注释添加到@Dan Menes 答案，因为它属于那里，但 cmets 不允许我进行格式化，Myst 语法对换行符敏感，并且 cmets 的字符数有限。因此，我将其作为单独的答案发布，即使它与现有答案相关。

要包含在 Myst 中，您必须稍微不同的格式：

```{include} ../main/post_installation_windows.md
```

它也可以包装自己来做 reStructured 标记（然后包含的文件将被视为在 restructured 中写入）：

```{eval-rst}
.. include:: snippets/include-rst.rst
```

但是，使用本机 Myst 语法更容易。而且它有更好的特性，例如，仅仅包含文件不会正确解析被包含文件中的任何引用，而 include-literal 应该：

```{include-literal} ../../example.md
:language: md
```

你可能会发现包含一个简单的文档是可以的，但是包含一个有很多引用的复杂文档会导致更多的麻烦，所以我会推荐实验性的include-literal（从版本 0.12.7）

参考： https://myst-parser.readthedocs.io/en/latest/using/howto.html

【讨论】：

【解决方案8】：

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

【讨论】：