Adding subsections of self in the toctree
python-sphinx, restructuredtext, sections, toctree
Solution
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.
Problem
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).