How to include a local table of contents into Sphinx doc?

Question

How to include a local table of contents into Sphinx doc?

I tried

.. toc:: 

But that doesn't seem to have any effect: nothing is inserted in the document.

Basically I need links to the sections in the current page to be placed at a certain location of each page.

Is this possible?

Solution 1

I'm not 100% sure this is what you're looking for, but the .. contents:: directive may help. By default, it'll give you the headings for the whole page, wherever you put the directive. With :local: specified, it will generate a local TOC for the headings below where you put the directive (handy for sub-section tocs).

.. contents:: Table of Contents
    :depth: 3

More details here: http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents

Solution 2

I had more luck with:

.. contents:: Table of Contents
   :depth: 1
   :local:
   :backlinks: none

The backlinks gets rid of the annoying links back from the headings to the toc.