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

@@ -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

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 }

docs/api/index.rst

@@ -11,5 +11,6 @@ API Documentation
    querying
    transformations
    utilities
+   typing
    exceptions
    extending

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
 ~~~~~~~~~~~~~~~
 

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

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",
 }