python - 如何添加目录树条目？

Question

我正在尝试开始使用 Sphinx 来记录 Python，但我似乎缺少一些非常基本的入门步骤。

我正在关注 http://www.sphinx-doc.org/en/stable/tutorial.html并已安装和配置(尽可能使用默认设置)该工具。

问题是我无法将另一个 RST 文件链接到索引。我的索引文件如下:

Welcome to FirstProject's documentation!
====================================
.. toctree::
   :maxdepth: 2

intro

请注意，intro.rst 与以下内容位于同一目录中:

Introduction to the FirstProject project!!
======================================

.. toctree::
    :maxdepth: 2

输出类型为html。当我尝试

make html

我收到一条警告:

/home/ngk/Code/Projects/Twitter/botscore/doc/intro.rst: WARNING: document isn't included in any toctree

我希望在 index.html 中创建一个带有“介绍”字符串的超链接，该链接指向 intro.html

相反，index.html 文件中的预期位置只有一个字符串“intro”。请注意，已创建 intro.html 文件，但未从 index.html 超链接

有人可以建议我错过了什么看似很小的步骤吗？

Answer 1

看起来问题出在 Sphinx-doc 期望包含的 RST 的每一行开头有 3 个空格。如下更改我的 index.rst 解决了问题!

.. toctree::
   :maxdepth: 2

   intro

Sphinx-doc 似乎对空格的确切数量很敏感。我尝试使用更少的选项，也尝试使用制表符空间，但都没有用。

希望这对遇到此问题的其他人有用。

编辑:它也适用于其他数量的空格，只要目录树中的每个条目都具有相同数量的空格。