106

我正在使用 Sphinx 来记录一个非 Python 项目。我想./doc在每个子模块中分发文件夹，其中包含submodule_name.rst用于记录该模块的文件。然后，我想将这些文件吸入主层次结构中，为整个设计创建规范。

IE： 

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

4

8 回答 8

127

是的你可以！

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

于 2013-06-20T14:58:10.937 回答
13

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

来自sphinx-dev 邮件列表：

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

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

于 2012-04-18T13:48:33.420 回答
10

在 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:
于 2017-08-30T06:10:24.937 回答
2

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

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

    conf.py：

    import os import sys sys.path.insert(...

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

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

于 2020-04-13T18:30:26.740 回答
1

也可以将 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('..'))
于 2015-09-07T08:09:17.153 回答
1

不需要创建存根文件的另一种技术是在您的目录树根中使用绝对引用（以 开头），并在调用时将源目录设置为最低的共同祖先。示例目录布局：/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。

于 2021-03-10T07:12:25.400 回答
1

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

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

要包含在 Myst 中，您必须对其进行稍微不同的格式化：

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

它也可以包装自己来做 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

于 2021-05-06T12:33:19.903 回答
0

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

于 2012-04-18T12:46:23.730 回答