Add support for sidebar-links directive. Ref jaraco/skeleton#77.

docs/conf.py

@@ -36,6 +36,7 @@
 extensions += ['sphinx.ext.intersphinx']
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/stable/', None),
 }
 
 # Preserve authored syntax for defaults

jaraco/packaging/sphinx.py

@@ -10,6 +10,10 @@
 
 from build.util import project_wheel_metadata as load_metadata
 from jaraco.context import suppress
+import sphinx.util.docutils
+from docutils.parsers.rst import directives
+import docutils.statemachine
+import domdf_python_tools.stringlist
 
 try:
     import importlib.metadata as metadata
@@ -22,9 +26,65 @@ def setup(app):
     app.connect('builder-inited', load_config_from_setup)
     app.connect('builder-inited', configure_substitutions)
     app.connect('html-page-context', add_package_url)
+    app.add_directive("sidebar-links", SidebarLinksDirective)
     return dict(version=metadata.version('jaraco.packaging'), parallel_read_safe=True)
 
 
+class SidebarLinksDirective(sphinx.util.docutils.SphinxDirective):
+    """
+    Directive which adds a toctree to the sidebar containing links to the project home
+    and PyPI repo.
+    """
+
+    has_content: bool = True
+
+    option_spec = {
+        "pypi": directives.flag,
+        "home": directives.flag,
+        "caption": directives.unchanged_required,
+    }
+
+    def run(self):
+        """
+        Create the installation node.
+        """
+
+        if self.env.docname != self.env.config.master_doc:
+            return []
+
+        body = domdf_python_tools.stringlist.StringList(
+            [
+                ".. toctree::",
+                "    :hidden:",
+            ]
+        )
+
+        with body.with_indent("    ", 1):
+            body.append(f":caption: {self.options.get('caption', 'Links')}")
+            body.blankline()
+
+            if "home" in self.options:
+                body.append(f"Home <{self.env.config.package_url}>")
+            if "pypi" in self.options:
+                body.append(
+                    f"PyPI <https://pypi.org/project/{self.env.config.project}>"
+                )
+
+            body.extend(self.content)
+
+        body.blankline()
+        body.blankline()
+
+        only_node = sphinx.addnodes.only(expr="html")
+        content_node = docutils.nodes.paragraph(rawsource=str(body))
+        only_node += content_node
+        self.state.nested_parse(
+            docutils.statemachine.StringList(body), self.content_offset, content_node
+        )
+
+        return [only_node]
+
+
 @suppress(KeyError)
 def _load_metadata_from_wheel():
     """

newsfragments/+517b55af.feature.rst

@@ -0,0 +1 @@
+Add sidebar-links directive.

setup.cfg

@@ -22,6 +22,8 @@ install_requires =
 	# virtualenv extra due to pypa/build#266
 	build[virtualenv]
 	jaraco.context
+	sphinx
+	domdf-python-tools
 
 [options.packages.find]
 exclude =
@@ -46,6 +48,7 @@ testing =
 	pytest-ruff
 
 	# local
+	types-docutils
 
 docs =
 	# upstream