sphinx 可以链接到位于 .rst 文档上方一个路径中的文档吗？答案

【问题标题】：Can sphinx link to documents that are located in one path above the .rst document?sphinx 可以链接到位于 .rst 文档上方一个路径中的文档吗？
【发布时间】：2020-08-16 18:31:13
【问题描述】：

我正在尝试使用 Sphinx 的基础知识来记录一个小项目。但我无法让他找到上面目录中的文件。

项目结构如下：

/用户/机器/工作区/project1

├── BDRespostas.py
├── constantes.py
├── docs
│   ├── conf.py
│   ├── index.rst
│   └── make.bat
├── estatisticas.py
├── migrate_postgre_sqlite.py
├── preProcessamentoTextual.py
└──

并且我尝试了多种方式配置 index.rst，均未成功：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   :ref:'estatisticas.py'
   ../BDRespostas.py
   '/Users/machine/workspace/project1/constantes.py'

我还结合了几次尝试，将 sys.path.insert() 添加到项目目录中。如果您已经设法提供此参考并可以帮助我，我真的很感激。

【问题讨论】：

toctree 条目是 RST 文件的名称。您不能使用 toctree 链接到 Python 模块。见stackoverflow.com/q/45195363/407651。
感谢收听@mzjn，我阅读了您的回复。我明白我不能以这种方式放置 .py 。我去了文档，但我找不到如何做到这一点，把我想要记录的 .py 文件。我会继续搜索。
@erfelipe 您正在使用没有src 目录的项目布局，here is one example。将.rst 文件视为中间文件：.py -> .rst -> .html。您可以使用sphinx-apidoc 创建.rst 文件（查看示例），或者您可以手动创建.rst 文件。 Sphinx 将使用 .rst 文件从 .py 模块中提取文档字符串。
如果您只是想包含位于 docs 目录之外的文件，您可以使用支持相对路径的 restructuredtext 的正常包含指令[1]。 [1]：docutils.sourceforge.io/docs/ref/rst/…

标签： python python-sphinx toctree

【解决方案1】：

如上所述，toctree 用于包含文档（.rst 文件），而不是 Python 源代码。告诉我们您想要达到的目标。

不要掩饰它 - toctree 只能包含来自当前文件夹或子文件夹的文档。 IE。你不能

.. toctree::
   
   ../one.rst
   ../two/three.rst

【讨论】：