How to add a toctree entry?

Question

I am trying to get started with Sphinx for documenting Python, and I seem to be missing some very basic step in getting started.

I'm following the http://www.sphinx-doc.org/en/stable/tutorial.html and have installed and configured (with defaults, wherever possible) the tool.

The problem is that I am unable to link another RST file to index. My index file is as below:

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

intro

Note that intro.rst is in the same directory with the following content:

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

.. toctree::
    :maxdepth: 2

The output type is html. When I try

make html

I get a warning saying:

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

I expected that a hyperlink with 'the intro' string would be created in index.html with the link pointing to intro.html

Instead, there is just a string 'intro' in the expected location in the index.html file. Note that the intro.html file is created, but not hyperlinked from index.html

Can someone suggest what seemingly small step I have missed?

Answer 1

It looks like the problem was that Sphinx-doc was expecting 3 whitespaces at the start of each line of the included RSTs. Changing my index.rst as below fixed the problem!

.. toctree::
   :maxdepth: 2

   intro

Sphinx-doc seems to be sensitive to the exact number of whitespaces. I tried using fewer and also tried using a tabspace, but neither worked.

Hope this is useful to others who come across this problem.

Edit: It works with other numbers of whitespaces too, as long as each entry in the toctree has the same number of whitespaces.