1

I'm using Sphinx's HTML builder with the Read The Docs theme.

I'm trying to build a technical documentation for a project where each page corresponds to a "component", and each "component" may link to "subcomponents" hierarchically, making the whole documentation recursive:

Component 1
***********

Subcomponents
=============

.. toctree::
    component_2
    component_3

Section A
=========

Subsection a
^^^^^^^^^^^^

Subsubsection i
~~~~~~~~~~~~~~~

However, Sphinx more or less expects the root document to be a dumb ToC, so it gives me the following sidebar structure:

Component 2
  Subcomponents
  Section A
    Subsection a
      Subsubsection i
Component 3
  Subcomponents
  Section A
    Subsection a
      Subsubsection i

Instead of the one I'd like:

Subcomponents
  Component 2
    Subcomponents
    Section A
      Subsection a
        Subsubsection i
  Component 3
    Subcomponents
    Section A
      Subsection a
        Subsubsection i
Section A
  Subsection a
    Subsubsection i

Edit: For this MWE, I have used a flat directory structure:

_static
conf.py
component_1.rst # root_doc
component_2.rst
component_3.rst

For completeness' sake, I have also tried a directory structure that matches the logical structure (updating toctree links as required), with the same result:

_static
conf.py
index.rst # component_1, root_doc
component_2
`-index.rst # component_2
component_3
`-index.rst # component_3

So far, I have tried a few workarounds, none of which is entirely satisfying:

Dummy root document

I tried creating a dummy root document containing:

.. toctree::
    component_1

This approach has the following drawbacks:

  • The home page of my documentation is now the equivalent of a sitemap.
  • The existence of a dummy root document alters the navigation of the documentation (back/forward buttons and top breadcrumbs), so I can't really hide the home page away.
  • The sidebar structure is still not exactly the one I want:
Component 1
  Subcomponents
    Component 2
      Subcomponents
      Section A
        Subsection a
          Subsubsection i
    Component 3
      Subcomponents
      Section A
        Subsection a
          Subsubsection i
  Section A
    Subsection a
      Subsubsection i

I can improve things somewhat by running sed on the HTML output to replace all links to the root document (e.g. the link under the project icon) to links to Component 1 and erase the first level of the sidebar hierarchy, but the navigation issues remain.

Hidden toctrees

I tried using hidden toctrees to build the document hierarchy, and inserting the links manually to get the result I wanted.

The root document ends up modified as follows:

Component 1
***********

Subcomponents
=============

.. toctree::
    :hidden:
    :caption: Subcomponents
    component_2
    component_3

:doc:`component_2`

:doc:`component_3`

Section A
=========

.. toctree::
    :hidden:
    :caption: Section A
    Subsection a <#subsection-a#http://>
    Subsubsection i <#subsubsection-i#http://>

Subsection a
^^^^^^^^^^^^

Subsubsection i
~~~~~~~~~~~~~~~

This approach has the following drawbacks:

  • I can't reuse the same template for the root document as for the other documents.
  • The document body looks identical, but as the underlying classes are all different, I'm one bad CSS update away from breaking my root document.
  • The sidebar structure is not the one I want, either. I can live with the top-level sections (actually the caption of the toctrees) not being clickable, but losing the indentation and the "you are here" highlighting is a dealbreaker:
Subcomponents (not clickable)
Component 2
  Subcomponents
  Section A
    Subsection a
      Subsubsection i
Component 3
  Subcomponents
  Section A
    Subsection a
      Subsubsection i
Section A (not clickable)
Subsection a
Subsubsection i (not indented)

My question, therefore, is: is there a better workaround to get the result I want, or should I take my chances with a feature request for Sphinx?

user16785526
  • 131
  • 1
  • 6
  • 1
    You did not include your docs directory structure, which would be helpful to diagnose the issue and suggest options. Please edit your question to include it. I would create a directory structure that reflects the nested navigation structure you desire. Each directory would contain an `index.rst` that contains a `toctree` for the files in that directory as well as to the next level down. The RTD theme should pick up the nesting and render the nav accordingly. – Steve Piercy Oct 01 '22 at 04:32
  • @steve-piercy, I have added a section on the directory structure I used for my MWE. I have also documented the result of trying out your suggestion (no luck). This doesn't surprise me, as the Sphinx document structure only hinges on the `toctree` directives, and is independent from the underlying directory structure. – user16785526 Oct 04 '22 at 08:25
  • I cannot make sense of your revision. Sorry. It is best to create a [MRE](https://stackoverflow.com/help/minimal-reproducible-example) in a public repository that can be cloned and docs built locally, and share that. – Steve Piercy Oct 05 '22 at 11:47

0 Answers0