docs(sphinx): preserve domain terms and clean reference docs warnings

Author: jaelliot

docs/conf.py

@@ -27,9 +27,9 @@
 except ImportError:
     sphinx_rtd_theme = None
 
-project = 'keri'
-copyright = '2022 - 2026, Dr. Samuel Smith and contributors'
-author = 'Dr. Samuel Smith'
+project = "keri"
+copyright = "2022 - 2026, Dr. Samuel Smith and contributors"
+author = "Dr. Samuel Smith"
 
 version = release = keri.__version__
 
@@ -39,22 +39,104 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'myst_parser',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',
+    "myst_parser",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
 ]
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 napoleon_include_init_with_doc = True
 
+# Preserve KERI domain language in docstrings by mapping frequently used
+# domain terms to canonical symbols. This avoids forcing prose rewrites.
+napoleon_type_aliases = {
+    "Serder": "keri.core.serdering.Serder",
+    "SerderKERI": "keri.core.serdering.SerderKERI",
+    "SerderACDC": "keri.core.serdering.SerderACDC",
+    "Diger": "keri.core.coring.Diger",
+    "Saider": "keri.core.coring.Saider",
+    "Siger": "keri.core.coring.Siger",
+    "Cigar": "keri.core.coring.Cigar",
+    "Prefixer": "keri.core.coring.Prefixer",
+    "Verfer": "keri.core.coring.Verfer",
+    "Seqner": "keri.core.coring.Seqner",
+    "Number": "keri.core.coring.Number",
+    "Tholder": "keri.core.coring.Tholder",
+    "Kever": "keri.core.eventing.Kever",
+    "Kevery": "keri.core.eventing.Kevery",
+    "Parser": "keri.core.parsing.Parser",
+    "Router": "keri.core.routing.Router",
+    "Revery": "keri.core.routing.Revery",
+    "Hab": "keri.app.habbing.Hab",
+    "GroupHab": "keri.app.habbing.GroupHab",
+    "Habery": "keri.app.habbing.Habery",
+    "KeyStateRecord": "keri.recording.KeyStateRecord",
+    "EndpointRecord": "keri.recording.EndpointRecord",
+    "LocationRecord": "keri.recording.LocationRecord",
+    "Deck": "hio.help.decking.Deck",
+    "Versionage": "keri.kering.Versionage",
+}
+
+# Resolve common external symbols from their upstream docs inventories.
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "falcon": ("https://falcon.readthedocs.io/en/stable/", None),
+}
+
+# Preserve legacy/domain-rich terminology in docstrings without forcing
+# destructive content rewrites to satisfy unresolved Python cross-references.
+# Keep structural/docutils warnings visible in separate cleanup lanes.
+suppress_warnings = ["ref.class", "ref.exc", "ref.obj"]
+
+# Keep domain-specific docstring type names intact while suppressing unresolved
+# cross-reference warnings for symbols that are not import-resolvable by Sphinx.
+nitpick_ignore = [
+    ("py:class", "SerderKERI"),
+    ("py:class", "serdering.SerderKERI"),
+    ("py:class", "SerderKeri"),
+    ("py:class", "serving.Client"),
+    ("py:class", "TCP Client"),
+    ("py:class", "TCP Remoter"),
+    ("py:class", "Habitat"),
+    ("py:class", "Client"),
+    ("py:class", "Request"),
+    ("py:class", "Response"),
+    ("py:class", "Serder"),
+    ("py:class", "serdering.Serder"),
+    ("py:class", "hicting.Mict"),
+    ("py:class", "OrderedSet"),
+    ("py:class", "oset.OrderedSet"),
+    ("py:class", "decking.Deck"),
+    ("py:class", "collections.abc.Iterable"),
+    ("py:class", "falcon.App"),
+    ("py:class", "serder is SerderKERI instance of"),
+    ("py:class", "serder is SerderKERI instance"),
+    ("py:exc", "ValidationError"),
+    ("py:exc", "ConfigurationError"),
+    ("py:exc", "MissingEntryError"),
+    ("py:exc", "ClosedError"),
+    ("py:exc", "AuthError"),
+    ("py:exc", "KeriError"),
+    ("py:obj", "datetime"),
+]
+
+# Many unresolved references are phrase-like parser artifacts from legacy
+# docstrings/autosummary output (for example targets containing spaces). Keep
+# this conservative to avoid muting real symbol regressions.
+nitpick_ignore_regex = [
+    ("py:class", r".*\s+.*"),
+    ("py:obj", r".*\s+.*"),
+]
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -68,4 +150,4 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]

docs/readme.rst

@@ -101,5 +101,14 @@ Testing
   pytest tests/demo/
 
 
+Documentation Build Notes
+-------------------------
+* Build docs from :bash:`docs/` with :bash:`make html`.
+* Keep canonical KERI domain terms in docstrings and reference docs. Do not
+  rename domain vocabulary only to satisfy cross-reference resolution.
+* Sphinx reference resolution policy for domain terminology is managed in
+  :bash:`docs/conf.py`.
+
+
 
 

ref/Peer2PeerCredentials.md

@@ -266,7 +266,7 @@ KERI Message: `exn` for peer to peer exchanges.
 
 ### Verifiable Credential with CESR Proof Format
 
-```json=
+```text
 {
    "x": "EZllThM1rLBSMZ_ozM1uAnFvSfC0N1jaQ42aKU5sCZ5Q",
    "d": {

ref/PythonStyleGuide.md

@@ -49,14 +49,18 @@ DocStrings:
    such as this string. Embedded strings use 'single quotes'.
    """
 
-   Format for code documentation in the the Google flavor of sphinx.ext.napolean format.
+   Format for code documentation in the the Google flavor of sphinx.ext.napoleon format.
    See
    https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
    and
    https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google
 
    Napoleon supports two styles of docstrings: Google and NumPy. The main difference between
    the two styles is that Google uses indentation to separate sections, whereas NumPy uses underlines.
+
+   Preserve KERI domain terminology in docstrings and reference text.
+   If a domain term does not map cleanly to a Python import path for Sphinx cross-references,
+   handle the resolution policy in docs/conf.py instead of renaming the domain term.
 ```
    Google style:
 

ref/getting_started.md

@@ -460,7 +460,7 @@ Indirect mode needs supporting infrastructure like witness and validators to fun
 
 ## Event Life Cycle
 
-#### Creating An Inception Event Message
+### Creating An Inception Event Message
 Creating an event message involves appending count code prefixes and signatures to an event object.
 There is a function that will handle all this for you called messagize().
 ```python
@@ -487,7 +487,7 @@ with dbing.openLMDB(name="edy") as db, keeping.openKS(name="edy") as kpr:
     print()
 ```
 
-#### Signing An Inception Event
+### Signing An Inception Event
 In order for an event to be valid it must be signed.  The Manager object can be used to sign an event. This will create
 signatures, but they are not yet attached to the event.  See the section below for how to attach them to the event by
 creating an event message.
@@ -514,7 +514,7 @@ with dbing.openLMDB(name="edy") as db, keeping.openKS(name="edy") as kpr:
     sigers = mgr.sign(ser=srdr.raw, verfers=verfers)
 ```
 
-#### Verifying An Inception Event Message
+### Verifying An Inception Event Message
 ```python
 import keri.core.eventing as eventing
 import keri.core.coring as coring
@@ -551,7 +551,7 @@ with dbing.openLMDB(name="edy") as db, keeping.openKS(name="edy") as kpr:
     print()
 ```
 
-#### Rotating Keys
+### Rotating Keys
 
 ```python
 import keri.core.eventing as eventing
@@ -587,9 +587,9 @@ with dbing.openLMDB(name="edy") as db, keeping.openKS(name="edy") as kpr:
     print()
 ```
 
-#### Interaction
+### Interaction
 
-#### Abandonment
+### Abandonment
 Abandonment or revocation is a subset of rotation.  KERI events always include a pre rotated key.  To abandon an
 identifier a rotation event is created and the pre rotated key is set to an empty string or null.
 

ref/tel.md

@@ -79,7 +79,8 @@ references to Schema. The Management TEL will have two events: `vcp` for Registr
 for rotation of the list or Registrars. The events will reference the controlling identifier in the `ii` field and be
 anchored to the KEL with an event seal triple attachment.
 
-The Registry specific identifier will be self-addressing (see [below](#self-addressing-Identifiers)
+The Registry specific identifier will be self-addressing (see below in the
+"Self Addressing Identifiers" section
 for definition) using its inception data for its derivation. This requires a commitment to the anchor in the controlling
 KEL and necessitates the event location seal be included in the event. The derived identifier is then set in the `i`
 field of the events in the management TEL.