Search code examples
python-sphinxrestructuredtexttoctree

Managing Sphinx toctrees combined with inline sections

I'm trying to learn how I can manage a toctree element that is located in the same file as other content.

Suppose I have a thingamajig.rst chapter that looks like this:

Thingamajigs
============

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

Overview
++++++++

Thingamajigs are fun

When I render it --- foo/bar/baz have their own .rst files --- it looks like this:

enter image description here

But if I move the Overview section before the toctree, then it pushes the toctree down into the Overview section:

Thingamajigs
============

Overview
++++++++

Thingamajigs are fun

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

enter image description here

Is there any way to have my toctree after the Overview section, but located under the Thingamajigs section?

Alternatively, can I do something like this?

Thingamajigs
============

.. toctree::
   :maxdepth: 2

   Overview          <-- refers to Overview section in same file
   foo
   bar
   baz

Overview
++++++++

Thingamajigs are fun
Solution

  • The section headings hierarchy is simply the order as encountered. So your ==== underline sets the title ("H1") and ++++ underline sets the subtitle ("H2") for this page only. Depending what layout you're after...

    A. Maybe you wanted a "Table of contents" section as a sibling of the "Overview" section (both within "Thingamajigs" parent), so insert a new H2 section heading:

    Thingamajigs
============

Overview
++++++++

Thingamajigs are fun


Table of contents
+++++++++++++++++

.. toctree::
    :maxdepth: 2

    foo
    bar
    baz

    B. Or maybe you don't want "Overview" in the section headings hierarchy at all, so highlight it by a different means:

    Thingamajigs
============

.. admonition:: Overview

    Thingamajigs are fun

.. toctree::
    :maxdepth: 2

    foo
    bar
    baz

    C. Or list the headings hierarchy within this page, separately from external pages:

    .. contents:: In this page
    :local:

.. beware, that contents directive must appear before any heading hierarchy

Thingamajigs
============

.. toctree::
    :maxdepth: 2
    :caption: In other pages
    
    foo
    bar
    baz

    D. Or do exactly what your last example showed: move the "Overview" content out to a separate ReST document and include its name in the toctree directive body.