Adding subsections of self in the toctree

Question

I am having an issue with getting the table of contents (TOC) to display subsections of the front page of my documentation.

I have a number of sections on my front page, and I would like these to be displayed in the TOC. The display of subsection works fine for every other page included in the TOC, but not self.

My index.rst code:

=====
Title
=====

Subsection
----------

Some documentation.

Contents
--------

.. toctree::
   :maxdepth: 2

   self
   development

What I would expect to see in the TOC is this:

• Title
  • Subsection
  • Contents
• Development
  • Subsection

Instead what I get is this:

• Title
• Development
  • Subsection

I have found one solution so far, but it is not really satisfactory. I can put all the content in a separate page, then include the content in index.rst using an .. include: directive, and put the separate page in the TOC. This makes the TOC look right, but creates a duplicate page, which is now included in the navigation (previous/next page).

Ghats

Answer 1

There are several issues with the section layout in the question:

Instead what I get is this:

• Title
• Development
  • Subsection

Using self as a toctree entry makes the outermost section title of the containing .rst file be included in that line of the toctree entry. The self entry will not render sub-sections or sibling sections, only the outermost section title. This goes against the usual properties of toctree entries.

Two resulting consequences of the above can immediately be noticed in the example from the question:

• title and development are incorrectly rendered as being on the same level in the section hierarchy. When a .rst file is included in a toctree, its sections are placed below in the section hierarchy to the section the toctree directive is declared in.

• title will be repeated twice, as being on different levels, if the containing .rst is placed in an exterior toctree.

Corresponding title.rst:

=====
Title
=====

Subsection
----------

Some documentation.

Contents
--------

.. toctree::
   :maxdepth: 2

   self
   development

Corresponding development.rst:

development
===========

some text

Subsection inside development.rst
---------------------------------

Corresponding exterior.rst:

Exterior
========

.. toctree::
    :maxdepth: 4

    title

---

---

It's not a good design choice to aim for a section structure that works against the properties of the toctree directive. From the specification in the question, the simplest and conceptually soundest solution is to use the contents directive to list the sections within one given .rst document.

What I would expect to see in the TOC is this:

• Title
  • Subsection
  • Contents
• Development
  • Subsection

The easiest choice is using separate files title.rst and development.rst putting them in the same level in the index.rst toctree.

Corresponding index.rst:

Exterior
========

.. toctree::

    title
    development

---

---

To achieve tree of references both internal and external to a given .rst file the best solution is to use a simple bullet list of hyperlink targets.

Corresponding title.rst:

.. _target_title:

=====
Title
=====

.. _target_subsection_title:

Subsection inside title.rst
---------------------------

Some documentation.

.. _target_contents:

Contents
--------

text

- :ref:`Title <target_title>`

 - :ref:`Subsection <target_subsection_title>`

 - :ref:`Contents <target_contents>`

- :ref:`Development <target_development>`

 - :ref:`Subsection <target_subsection_development>`

Corresponding development.rst:

.. _target_development:

development
===========

some text

.. _target_subsection_development:

Subsection inside development.rst
---------------------------------

Corresponding exterior.rst:

Exterior
========

.. toctree::
    :maxdepth: 4

    title
    development

---

---

then include the content in index.rst using an .. include: directive

Use of the .. include:: directive would only change the place of the toctree problems without entirely solving them.

Dunton

Answer 2

You could use the TOC directive from reStructuredText directly:

.. contents::

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

Bellis