Python sphinx是否可以链接到不位于根文档下目录中的文档？

我正在使用Sphinx来记录一个非Python项目。我想在每个子模块中分发

/doc

文件夹，其中包含

子模块_name.rst

文件以记录该模块。然后，我想将这些文件吸收到主层次结构中，为整个设计创建规范

即：

我试图在主

项目规范rst

文档目录树中包含以下文件：

。。目录树：：
：编号：
：maxdepth:2
单元1

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

警告：目录树包含对不存在的文档u'modules/module1/docs/module1'的引用

是否无法在文档路径中使用

。/

更新：添加了conf.py位置

更新：

---

除了下面的include技巧之外，这（2019年）仍然是不可能的。有一个未解决的问题一直在向前推进：

一个解决方案，如果真的不可能使用备份

的相关链接。

就是我可以使用

shutil

将文件复制到规范的

conf.py

中的规范文件夹树中，但除非绝对必要，否则我不希望有多个副本。

答案似乎是否定的，toc树中列出的文档必须位于目录中，即包含您的和

conf.py

（以及任何子目录）的目录

从：

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

因此，您可以尝试向

Project/docs/spec

目录中的所有模块添加符号链接，而不是使用

shutil

复制文件。如果您创建一个指向

项目/模块

的符号链接，那么您可以在toc树中将这些文件简单地引用为

模块/module1/docs/module1

等。

是的，您可以

代替符号链接（在Windows上不起作用），创建一个存根文档，其中除了

之外没有任何内容。。包括：：

指令

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

自述链接.rst

的文件中：

.. include:: ../README

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

然后在

index.rst

中，我将目录树设置为：

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

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

---

感谢您的建议

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

对于windows，我将所有sphinx文件和目录（index.rst除外）移动到文档/并更改：

docs/make.bat

：更改

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

到

docs/conf.py

：添加

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

---

在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文件夹中的my index.rst中：

Contents:

.. toctree::
   :maxdepth: 4

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

---

我解决了我非常相似的问题，不同之处在于我想包括一个外部jupyter笔记本。我已经安装了nbsphinx，但无法使其工作。 什么不起作用：

我有一个目录，我想在路径中包含根目录：

conf.py：

导入操作系统
导入系统
sys.path.insert（…

使用

.include:：指令

文件已包含在文档中，但仍按原样

---

最后，解决的问题是安装软件包

使用一种不需要创建存根文件的替代技术（从

/

开始）在目录树根目录中，并在调用

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

：

.. include:: ../README

.. 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 build-c-b html-D masterdoc=b/x/index/path/to/common/consent

---

我用sphinx

3.0.2

测试了这一点，我的答案本质上是@Dan Menes，但对于Myst解析器，而不是重构的

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

要包含在Myst中，您必须稍微改变格式：

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

它也可以包装自己来进行重新构造的标记（然后包含的文件将被视为以重新构造的格式编写）：

但是，使用本机Myst语法更容易。而且它具有更好的功能，例如，仅包含文件将无法正确解析包含文件中的任何引用，而包含文字应：

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

您可能会发现，包含一个简单的文档是可以的，但是包含一个包含许多引用的复杂文档会引起更多的麻烦，因此我推荐实验性的

include literal

（来自版本0.12.7）

参考：

---

是否需要将

.rst

扩展名添加到行

模块1

？我不这么认为，因为在：中，因为其余源文件可以有不同的扩展名（有些人喜欢.txt，有些人喜欢.rst–扩展名可以配置为source\u后缀）不同的操作系统有不同的路径分隔符，Sphinx对它们进行了抽象：所有“文档名”都与源目录相关，扩展名被剥离，路径分隔符被转换为斜杠。好吧，猜猜看！所以我认为

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

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

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