Allow including nested captions in toctree
function provided to HTML theme templates
#10697
Labels
type:enhancement
enhance or introduce a new feature
Milestone
Is your feature request related to a problem? Please describe.
I'm exploring ways to enable more flexible/complex site structures with Sphinx, as part of a Sphinx theme (https://github.com/pradyunsg/lutra/). One of the useful bits of toctree metadata, that Sphinx does not include in the final markup, is all of captions for the not-top-level toctree items.
Currently, without this, certain navigational structures cannot be implemented -- eg: having top-level documents as tabs on the site and having their inner toctrees presented with captions in the sidebar (when that tab is active). Providing the nested toctree captions in the
toctree
directive would make it possible to implement such navifation structures.Describe the solution you'd like
Allow specifying a
captions_till_depth
argument, defaulting to 1, on thetoctree
context variable that behaves likemaxdepth
but trims captions instead. The toctree generation code would then be adapted to both (a) generate the toctree captions in the nested bullet list and (b) trim them based on this variable.Describe alternatives you've considered
include_captions
argument to thetoctree
context variable passed into the theme render context (and, add it toTocTree.get_toctree_for
). This will default to False -- preserving the current default behaviour. However, when it is set to True, the final markup will contain the caption nested within the rest of the document.Additional context
Look at the toctree presented. Note that it does not contain the inner-document's toctrees' captions (Aesthetics and Structural) but does contain the top-level-document's toctree's "Usage" caption. Screenshot of what is generated by alabaster:
The text was updated successfully, but these errors were encountered: