Add only headings of self to toctree

[evildmp]

I think that https://github.com/sphinx-doc/sphinx/issues/2103 is related, but I am opening this as a separate issue because perhaps the functionality described there as missing is not the only way to achieve this end.

Consider a landing page in the documentation, say of how-to guides, that has a number of sub-pages (each one is a particular how-to guide).

A good landing page

For the page body, a sensitive author will use headings, descriptions and multiple toctrees to provide a structured overview of the sub-pages' content, by using multiple toctree directives, one for each section of the page:

How-to guides

Installation and configuration

Integer feugiat scelerisque varius morbi enim nunc faucibus. Vel fringilla est ullamcorper eget. Pharetra vel turpis nunc eget lorem dolor. Dui vivamus arcu felis bibendum. Rhoncus mattis rhoncus urna neque viverra justo.

• Install in a VM
• Install with Docker
• Configure networking
• Configure flidgets
• Configure warbles

Production

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

• Deploy
• Scale
• Replicate instances
• Upgrade in place
• Decommission

Observability and performance

Vel eros donec ac odio tempor orci dapibus ultrices in. Sagittis vitae et leo duis. Pulvinar mattis nunc sed blandit libero. Faucibus purus in massa tempor nec feugiat nisl.

• Logging
• Monitoring
• Performance tuning

A poor menu

However, the navigation menu that's created does not benefit from this stucture, and by the time we get to more than about seven sub-pages, toctrees for that section of the navigation become rather unattractive and inconvenient to use - an undifferentiated list of items is a poor navigation interface.

A common pattern I see is a navigation menu that looks like:

• Home
• Tutorial
• How-to guides
  • Install in a VM
  • Install with Docker
  • Configure networking
  • Configure flidgets
  • Configure warbles
  • Deploy
  • Scale
  • Replicate instances
  • Upgrade in place
  • Decommission
  • Logging
  • Monitoring
  • Performance tuning
• Reference
• Explanation

This is well into the realm of being unwieldy, even with a certain amount of implict grouping. No user will enjoy working with that list.

A better menu

A much better pattern would be to add only the headings of the How-to landing page into the navigation menu:

• Home
• Tutorial
• How-to guides
  • Installation and configuration
  • Production
  • Observability and performance
• Reference
• Explanation

Achieving this requires two things:

• a toctree directive that add only the headings of self (strictly speaking, second-level headings and lower) into the toctree, but not display them in-situ in the page
• multiple toctree directives to list the particular sub-pages in each section, but not add them into the global navigation (an ordinary list of links could do this, but a toctree would be more elegant.

An alternative I've seen is to add another layer of nesting: a new landing page for each section of the how-to guides - but the result is an over-fussy and complex navigation structure.

[picnixz]

The usage of self seems to be an obscure feature (and personally I wasn't even aware of that!). While it's been added in 0.6, the doc doesn't have a clear example of how to use it.

The linked issue seems to include a workaround + a CSS fix for the workaround but I think we should indeed support what was requested originally. As for how to do it, I have no idea, so PR is welcomed.

Finally, I don't know if we should keep this issue open or not. We could keep it open because you have a nice example of what you want but on the other hand, the other issue has some workaround. Could you test the workaround and see if it does what you want? also, if it doesn't, we could keep this one open and anyone writing a PR should solve both issues at the same time.

[evildmp]

The linked issue seems to include a workaround + a CSS fix for the workaround but I think we should indeed support what was requested originally. As for how to do it, I have no idea, so PR is welcomed.

I don't think it's really a fix - it relies on display: none; to hide the unwanted things. So I think it does merit a real fix, that turns self into a more useful and powerful feature.

[picnixz]

Ah I meant that the fix is a fix for the workaround not the issue itself. So it's a hacky workaround but yes a real fix is welcome but I don't know how to do it.