Using self to create a sitemap with toctree in sphinx seem broken?

Question

I'm updating a FAQ for a fairly big project and I would like to add an index of the questions at the top of the page, so it becomes easier for users to find what they're looking for.

The Sphinx documentation toctree article states "The special entry name self stands for the document containing the toctree directive. This is useful if you want to generate a “sitemap” from the toctree." This is what I want. The problem is that self seem broken and only includes the current documents title and not the subtitles. It works correctly when I'm in another document and references the FAQ, only in the document itself does it fail.

To demonstrate

.. toctree::
   :maxdepth: 3

   faq

In other file results in

• Frequently Asked Questions
  • FAQ
    • Question 1
    • Question 2
    • Question 3
  • Non-obvious behaviour and other need to know

Inside faq

.. toctree::
   :maxdepth: 3

   self

results in

• Frequently Asked Questions

I've thought that maybe it was because sphinx wasn't aware of the subtitles when the toctree is converted and tried moving the toctree to the bottom of the page. No change.

Any ideas on how to include a index of a page in the page itself with sphinx would be greatly appreciated

Answer 1

What your are looking for is the contents directive.

Insert the following block after the title of your page to build the list of questions :

.. contents::
   :local:
   :depth: 1

It will produce:

• Question 1
• Question 2
• Question 3