Discussing and shaping the `linktree` directive

[amotl]

Hi there,

Introduction

Over at GH-11, we started to work ¹ on a linktree directive, somehow extending the capabilities of the venerable toctree directive, somehow going into different directions. This issue can be used to discuss this feature independently, and beyond the lifetime of the pull request.

We are looking forward to any kind of feedback or praise. Right now will be a good chance that your input can find a good chance to be considered on the next development iterations.

Preview

https://sphinx-design-elements--11.org.readthedocs.build/en/11/linktree.html

Credits

Last but not least, we would like send huge kudos to @pradyunsg for conceiving and maintaining the Furo theme, where the web representation of the "Link Tree" derives its machinery from. 💯

With kind regards,
Andreas.

References » Issues

• relative links in toctree sphinx-doc/sphinx#701
• Support autosorting a TOC sphinx-doc/sphinx#1430
• Intersphinx support in toctrees sphinx-doc/sphinx#1836
• Anchor support in toctree sphinx-doc/sphinx#2954
• Feature request: alternate titles for sidebar sphinx-doc/sphinx#3906
• request new feature for combining or extending toc-trees sphinx-doc/sphinx#4546
• Allow regex in toctree directive. sphinx-doc/sphinx#6650
• Allow to specify toctree pages as direct-children of parent page sphinx-doc/sphinx#8287
• Allow including nested captions in toctree function provided to HTML theme templates sphinx-doc/sphinx#10697
• Referencing indices from navigation doesn't work sphinx-doc/sphinx#11135
• Add support for toctree directive to include "backwards" path  sphinx-doc/sphinx#11462
• toctree with alphabetic "filter"  sphinx-doc/sphinx#11540

References » PRs

• Fix #701 by allowing title <hyperlink>_ toctree entries sphinx-doc/sphinx#1800
• Allow explicit markup in toctree directives sphinx-doc/sphinx#2354

Footnotes

1. Please note it is heavily work-in-progress, and its API or implementation may change before the initial release. ↩

[amotl]

Hi again. We did not go into that rabbit hole yet, but @bintoro apparently did on behalf of sphinx-navtree. Thank you so much. 🍀

Abstract

sphinx-navtree is a small Sphinx extension that lets you modify the documentation’s HTML navigation tree while keeping the underlying TOC structure intact.

There are a couple of things the extension can do:

• Optimize the presentation of top-level sections across output formats.
• Specify a maximum nesting depth for different parts of the nav tree.

Problem Description

The Read the Docs theme supports optional top-level headings that divide a documentation into its main sections (Manual and Demo Section in this documentation). They show up in the navigation pane and are rendered in all caps.
In reST markup, the headings are specified as caption options on the root toctree directives.

This works fine for the navigation menu. The trouble is that the captioned toctrees only appear to divide the content into top-level parts. Structurally, the layout in the example simply translates to consecutive chapters at the root level. This is because parallel toctrees do not establish separate branches in the Sphinx document tree:

The captions are really only annotations that have no bearing on the structure.

Now having learned that the captions are only visual dividers, and are not reflected in the actual document hierarchy, it becomes clear they will not appear anywhere outside of the navigation menu. Main sections defined in this way will not show up in PDF or EPUB outputs, the HTML breadcrumb navigation, or other representations of the full content layout.

Solution

sphinx-navtree solves the problem by letting you define the top-level structure as a proper hierarchy and converting that structure into captioned lists for nav tree rendering purposes only. This way, you make full use of the theme while ensuring the documentation is well-structured and renders correctly in all output formats.

When a template requests the global navigation tree, sphinx-navtree transforms it into one with captioned lists before it is rendered into HTML.

Essentially, the entire hierarchy is shifted up one level, with the two topmost levels merged into one. The end result is as if the structure had been specified like in the initial example — but only HTML navigation is affected. In other contexts the structure will be represented in full.

-- Source: https://sphinx-navtree.readthedocs.io/en/latest/transforms.html