From c57aef772cfcf59e82ed431a1a74a6dba8963387 Mon Sep 17 00:00:00 2001
From: Frank Sachsenheim <funkyfuture@riseup.net>
Date: Wed, 27 Dec 2023 23:27:57 +0100
Subject: [PATCH] docs/api: Adds section about type aliases and not so public
 interfaces

It was motivated to create targets for then hyperlinking type
annotations in the API docs. Turns out the second part doesn't work yet.
I assume that better practices around type documentation will evolve.
And it's still a usable reference that ranks high in searches.
---
 _delb/nodes.py          |  2 +-
 docs/_static/styles.css |  1 +
 docs/api/index.rst      |  1 +
 docs/api/nodes.rst      |  3 +++
 docs/api/typing.rst     | 41 +++++++++++++++++++++++++++++++++++++++++
 docs/conf.py            | 11 +++++++----
 6 files changed, 54 insertions(+), 5 deletions(-)
 create mode 100644 docs/api/typing.rst

diff --git a/_delb/nodes.py b/_delb/nodes.py
index 1616f0c..6dd16fb 100644
--- a/_delb/nodes.py
+++ b/_delb/nodes.py
@@ -344,7 +344,7 @@ class _TagDefinition(NamedTuple):
     Instances of this class describe tag nodes that are constructed from the context
     they are used in (commonly additions to a tree) and the properties that this
     description holds. For the sake of slick code they are not instantiated directly,
-    but with the :func:`tag` function.
+    but with the :func:`delb.tag` function.
     """
 
     local_name: str
diff --git a/docs/_static/styles.css b/docs/_static/styles.css
index ad3fb0d..ca74a6b 100644
--- a/docs/_static/styles.css
+++ b/docs/_static/styles.css
@@ -1,5 +1,6 @@
 article section dl.simple dd { margin-left: 0.618rem }  /* nested lists contain dd wrappers */
 #delb h1 + p img { vertical-align: top }  /* equally align non-/linking badges on the landing page */
+dl.py + p { margin-top: 2rem } p + dl.py { margin-top: 0 }  /* Improve spacing around class docs */
 img.sidebar-logo { max-height: 8rem }
 table.autosummary { box-shadow: none; width: 100% }
 table.autosummary tbody { vertical-align: top }
diff --git a/docs/api/index.rst b/docs/api/index.rst
index 8b776b1..7965f42 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -11,5 +11,6 @@ API Documentation
    querying
    transformations
    utilities
+   typing
    exceptions
    extending
diff --git a/docs/api/nodes.rst b/docs/api/nodes.rst
index 4c3dfec..dcfa45b 100644
--- a/docs/api/nodes.rst
+++ b/docs/api/nodes.rst
@@ -52,6 +52,9 @@ Node constructors
 Filters
 -------
 
+The following implementations are shipped with the library. Also see
+:class:`delb.typing.Filter`
+
 Default filters
 ~~~~~~~~~~~~~~~
 
diff --git a/docs/api/typing.rst b/docs/api/typing.rst
new file mode 100644
index 0000000..8b8b3a8
--- /dev/null
+++ b/docs/api/typing.rst
@@ -0,0 +1,41 @@
+:tocdepth: 2
+
+Type aliases & semi-public classes
+==================================
+
+There are internally used classes and type aliases that can be of interest for
+re-use in applications and extensions.
+
+Filter functions are defined as:
+
+.. autoclass:: delb.typing.Filter
+
+Loaders are defined as:
+
+.. autoclass:: delb.typing.Loader
+
+The order of loaders is defined with help of (read:
+``Loader | Iterable[Loader] | None``):
+
+.. autoclass:: delb.typing.LoaderConstraint
+
+Loaders may return a string that explains why it wouldn't successfully process
+the given input to the user:
+
+.. autoclass:: delb.typing.LoaderResult
+
+Namespace to prefix mappings are formalized as:
+
+.. autoclass:: delb.typing.NamespaceDeclarations
+
+All node classes inherit from a common class:
+
+.. class:: delb.NodeBase
+
+Methods that add nodes to a tree take a variety of input data:
+
+.. autoclass:: delb.typing.NodeSource
+
+Definitions that are used for convenient tree building are held in:
+
+.. autoclass:: _delb.nodes._TagDefinition
diff --git a/docs/conf.py b/docs/conf.py
index 32aa20d..992b2ac 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -211,10 +211,13 @@
 }
 
 autodoc_type_aliases = {
-    "Filter": "_delb.typing.Filter",
-    "LoaderResult": "_delb.typing.LoaderResult",
-    "NodeSource": "_delb.typing.NodeSource",
-    "_WrapperCache": "_delb.typing._WrapperCache",
+    "Filter": "delb.typing.Filter",
+    "Loader": "delb.typing.Loader",
+    "LoaderConstraint": "delb.typing.LoaderConstraint",
+    "LoaderResult": "delb.typing.LoaderResult",
+    "NamespaceDeclarations": "delb.typing.NamespaceDeclarations",
+    "NodeBase": "delb.NodeBase",
+    "NodeSource": "delb.typing.NodeSource",
 }