Add "link tree" element, using directive linktree

Author: amotl

CHANGES.md

@@ -30,7 +30,12 @@
 ## v0.2.0 - 2023-08-08
 
 - For dropdown elements that should exclusively open when toggled,
+<<<<<<< HEAD
   add a `dropdown-group` CSS class. Thanks, @kojinkai and @msbt.
+=======
+  add a `dropdown-group` CSS class
+- Add "link tree" element, using directive `linktree`
+>>>>>>> 1876b6b (Add "link tree" element, using directive `linktree`)
 
 ## v0.1.0 - 2023-07-19
 

docs/_templates/linktree-demo.html

@@ -0,0 +1,9 @@
+<h3>Classic toctree</h3>
+<div class="sidebar-tree">
+{{ sde_linktree_primary }}
+</div>
+
+<h3>Custom linktree</h3>
+<div class="sidebar-tree">
+{{ demo_synthetic_linktree }}
+</div>

docs/_templates/page.html

@@ -0,0 +1,10 @@
+{%- extends "!page.html" %}
+
+{% block content %}
+{{ super() }}
+
+{% if pagename == "linktree" %}
+{% include "linktree-demo.html" %}
+{% endif %}
+
+{% endblock %}

docs/conf.py

@@ -1,6 +1,12 @@
 """Configuration file for the Sphinx documentation builder."""
 
 import os
+import traceback
+import typing as t
+
+from sphinx.application import Sphinx
+
+from sphinx_design_elements.navigation import default_tree, demo_tree
 
 project = "Sphinx Design Elements"
 copyright = "2023-2024, Panodata Developers"  # noqa: A001
@@ -23,6 +29,9 @@
 # html_logo = "_static/logo_wide.svg"
 # html_favicon = "_static/logo_square.svg"
 
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
 # if html_theme not in ("sphinx_book_theme", "pydata_sphinx_theme"):
 #    html_css_files = [
 #        "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css"
@@ -33,6 +42,9 @@
         "sidebar_hide_name": False,
     }
 
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 myst_enable_extensions = [
     "attrs_block",
@@ -64,3 +76,28 @@
 }
 
 todo_include_todos = True
+
+def setup(app: Sphinx) -> None:
+    """Set up the sphinx extension."""
+    app.require_sphinx("3.0")
+    app.connect("html-page-context", _html_page_context)
+
+
+def _html_page_context(
+    app: Sphinx,
+    pagename: str,
+    templatename: str,
+    context: t.Dict[str, t.Any],
+    doctree: t.Any,
+) -> None:
+    """
+    Sphinx HTML page context provider.
+    """
+
+    # Initialize link tree navigation component.
+    try:
+        context["sde_linktree_primary"] = default_tree(builder=app.builder, context=context).render()
+        context["demo_synthetic_linktree"] = demo_tree(builder=app.builder, context=context).render()
+    except Exception as ex:
+        traceback.print_exception(ex)
+        raise

docs/get_started.md

@@ -64,6 +64,7 @@ provided by this collection, and how to use them in your documentation markup.
 
 - [](#gridtable-directive)
 - [](#infocard-directive)
+- [](#linktree-directive)
 - [](#tag-role)
 
 Both [reStructuredText] and [Markedly Structured Text] syntax are supported equally well.

docs/index.md

@@ -74,6 +74,7 @@ get_started
 gridtable
 infocard
 shield
+linktree
 ```
 
 ```{toctree}
@@ -134,6 +135,13 @@ Badge generator for Shields\.io, with optional target linking.
 A versatile hyperlink generator.
 :::
 
+:::{grid-item-card} {octicon}`workflow` Link tree
+:link: linktree
+:link-type: doc
+
+A programmable toctree component.
+:::
+
 :::{grid-item-card} {octicon}`tag` Special badges
 :link: tag
 :link-type: doc

docs/linktree.md

@@ -0,0 +1,128 @@
+(linktree-directive)=
+
+# Link Tree
+
+
+## About
+
+Similar but different from a Toc Tree.
+
+```{attention}
+This component is a work in progress. Breaking changes should be expected until a
+1.0 release, so version pinning is recommended.
+```
+
+### Problem
+
+So much work went into the toctree mechanics, it is sad that it is not a reusable
+component for building any kinds of navigation structures, and to be able to define
+its contents more freely.
+
+### Solution
+
+This component implements a programmable toc tree component, the link tree.
+
+
+## Details
+
+The link tree component builds upon the Sphinx [toc] and [toctree] subsystem. It provides
+both a rendered primary navigation within the `sde_linktree_primary` context variable
+for use from HTML templates, and a Sphinx directive, `linktree`, for rendering
+navigation trees into pages, similar but different from the [toctree directive]. The
+user interface mechanics and styles are based on [Furo]'s primary sidebar component.
+
+
+## Customizing
+
+Link trees can be customized by creating them programmatically, similar to how
+the `sde_linktree_primary` context variable is populated with the default Sphinx
+toc tree.
+
+The section hidden behind the dropdown outlines how the "custom linktree" is
+defined, which is displayed at the bottom of the page in a rendered variant.
+:::{dropdown} Custom linktree example code
+
+```python
+import typing as t
+
+from sphinx.application import Sphinx
+from sphinx_design_elements.lib.linktree import LinkTree
+
+
+def demo_tree(app: Sphinx, context: t.Dict[str, t.Any], docname: str = None) -> LinkTree:
+    """
+    The demo link tree showcases some features what can be done.
+
+    It uses regular page links to documents in the current project, a few
+    intersphinx references, and a few plain, regular, URL-based links.
+    """
+    linktree = LinkTree.from_context(app=app, context=context)
+    doc = linktree.api.doc
+    ref = linktree.api.ref
+    link = linktree.api.link
+
+    linktree \
+        .title("Project-local page links") \
+        .add(
+            doc(name="gridtable"),
+            doc(name="infocard"),
+        )
+
+    linktree \
+        .title("Intersphinx links") \
+        .add(
+            ref("sd:index"),
+            ref("sd:badges", label="sphinx{design} badges"),
+            ref("myst:syntax/images_and_figures", "MyST » Images and figures"),
+            ref("myst:syntax/referencing", "MyST » Cross references"),
+        )
+
+    linktree \
+        .title("URL links") \
+        .add(
+            link(uri="https://example.com"),
+            link(uri="https://example.com", label="A link to example.com, using a custom label ⚽."),
+    )
+
+    return linktree
+```
+:::
+
+```{todo}
+- Use the `linktree` directive to define custom link trees.
+- Link to other examples of custom link trees.
+- Maybe use `:link:` and `:link-type:` directive options of `grid-item-card` directive.
+```
+
+
+## Directive examples
+
+### Example 1
+
+The link tree of the `index` page, using a defined maximum depth, and a custom title.
+```{linktree}
+:docname: index
+:maxdepth: 1
+:title: Custom title
+```
+
+
+## Appendix
+
+Here, at the bottom of the page, different global template variables are presented,
+which contain representations of navigation trees, rendered to HTML.
+
+- `sde_linktree_primary`: The classic toctree, like it will usually be rendered
+  into the primary sidebar.
+- `demo_synthetic_linktree`: A customized link tree composed of links to project-local
+  pages, intersphinx links, and URLs, for demonstration purposes.
+
+```{hint}
+The corresponding template, `linktree-demo.html` will exclusively be rendered
+here, and not on other pages.
+```
+
+[Furo]: https://pradyunsg.me/furo/
+[toctree directive]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree
+[toc]: https://www.sphinx-doc.org/en/master/development/templating.html#toc
+[toctree]: https://www.sphinx-doc.org/en/master/development/templating.html#toctree

pyproject.toml

@@ -215,7 +215,7 @@ warn_unused_ignores = false
 warn_redundant_casts = true
 
 [[tool.mypy.overrides]]
-module = [ "docutils.*" ]
+module = ["docutils.*", "furo.*"]
 ignore_missing_imports = true
 
 [tool.versioningit.vcs]

sphinx_design_elements/compiled/style.css

@@ -88,3 +88,10 @@ hr.docutils {
 .bottom-margin-generous {
   margin-bottom: 2em !important;
 }
+
+/**
+ * Fix appearance of page-rendered link tree.
+**/
+article .sidebar-tree p.caption {
+  text-align: unset;
+}

sphinx_design_elements/extension.py

@@ -12,6 +12,7 @@
 from .gridtable import setup_gridtable
 from .hyper import setup_hyper
 from .infocard import setup_infocard
+from .linktree import setup_linktree
 from .shield import setup_shield
 from .tag import setup_tags
 
@@ -32,6 +33,7 @@ def setup_extension(app: Sphinx) -> None:
     setup_gridtable(app)
     setup_hyper(app)
     setup_infocard(app)
+    setup_linktree(app)
     setup_shield(app)
     setup_tags(app)