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‘ module/module1/docs/module1’的引用

是否有可能在文档路径中以某种方式使用 ../？

更新: 添加了 conp.py 位置

更新: 除了下面的包含技巧，这仍然是(2019)不可能的。有一个公开的问题一直在被推进，那就是 https://github.com/sphinx-doc/sphinx/issues/701

50768 次浏览
小开

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

小开

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

来自 Sphinx-dev 邮件列表:

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

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

小开
最佳答案

你可以的！

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

小开

It is also possible to configure sphinx to have only the index.rst file in the root and the all the other sphinx stuff in Project/docs:

对于 windows，我将所有的 sphinx 文件和 dir 文件(index.rst 除外)移动到 docs/中并更改:

改变

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

到

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

docs/conf.py: Add

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

在 config.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:
小开

我解决了我的相当类似的问题与差异，我想包括一个外部朱庇特笔记本电脑。我已经安装了 nbsphinx，但我不能让它工作。 失败之处:

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

    Py:

    import os 进口系统 Sys.path.insert (...

  2. 使用 .. include:: directive，该文件包含在文档中，但按原样进行。

最后什么 解决了的问题是安装软件包 Nbsphinx-link

小开

另一种不需要创建存根文件的技术是在 toctree 根目录中使用 绝对引用(从 /开始) ，并在调用 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>

我用狮身人面像 3.0.2做了测试。

小开

我的答案本质上是“ Dan Menes”，但是用于 Myst 解析器而不是“重构”。

我更愿意把它作为一个注释添加到@Dan Menes 的回答中，因为它属于那里，但是注释不允许我做格式化，Myst 语法对换行符很敏感，而且注释的字符数有限。所以我把它作为一个单独的答案发布出去，即使它与一个已有的答案有关。

为了包含在神秘中，你需要稍微改变一下格式:

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

它也可以包装自己来执行重新结构化的标记(然后包含的文件将被当作重新结构化的文件来处理) :

```{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


提交答案