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?
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.