6

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?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Karthick
  • 2,031
  • 1
  • 13
  • 18
  • 1
    The syntax of you directive `toctree` is not correct. All content of directive needs to be indented as much as the directive name is indented. In your case it's 3 spaces. – Paebbels Dec 09 '17 at 10:09

1 Answers1

7

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.

Karthick
  • 2,031
  • 1
  • 13
  • 18
  • 1
    It works with two spaces (or four) too. You just have to ensure that everything under `.. toctree::` is indented by the same amount, including the `:maxdepth: 2` option. – mzjn Dec 08 '17 at 16:20
  • Thanks for pointing this out. I seem to have messed up something in earlier trials. Like you said, it works with different number of spaces too, as long as all entries have the same indentation. – Karthick Dec 11 '17 at 04:46
  • Sorry to bump, since this solved the problem you should mark the answer as accepted to signal to users searching that his post has been solved. – bad_coder Oct 24 '20 at 17:05