From 7dbdf936ba20627aa4211f99d1d7e06ec9a5fd1c Mon Sep 17 00:00:00 2001
From: Marco Ricci <software@the13thletter.info>
Date: Sun, 29 Sep 2024 23:17:02 +0200
Subject: [PATCH] Enable cross-references on function signatures in
 documentation

When enabling `signature_crossrefs`, some default values use enumeration
values that we'd really like to have anchors for in the documentation.
(This also seems sensible for typing-only classes.)  We currently use an
"attributes" table in the class docstring for this purpose; build on
this by forcing MkDocs to render the respective class attribute too, via
an empty "docstring" for the attribute.

I considered enabling parameter headings, but these cannot be suppressed
from the table of contents, and the table of contents then starts
looking very cramped.
---
 mkdocs.yml                                 |  3 +--
 src/derivepassphrase/_types.py             | 25 +++++++++++++++++++++-
 src/derivepassphrase/exporter/storeroom.py |  5 +++++
 3 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 4f32a40..4e739ef 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -73,11 +73,10 @@ plugins:
           show_root_heading: true
           show_symbol_type_heading: true
           show_symbol_type_toc: true
-          parameters_heading: true
           members_order: 'source'
           show_signature_annotations: true
           separate_signature: true
-          signature_crossrefs: false
+          signature_crossrefs: true
           unwrap_annotated: true
         paths:
           - src
diff --git a/src/derivepassphrase/_types.py b/src/derivepassphrase/_types.py
index 9e59445..54d8dde 100644
--- a/src/derivepassphrase/_types.py
+++ b/src/derivepassphrase/_types.py
@@ -42,10 +42,13 @@ class VaultConfigGlobalSettings(TypedDict, total=False):
     """
 
     key: NotRequired[str]
+    """"""
     phrase: NotRequired[str]
+    """"""
     unicode_normalization_form: NotRequired[
         Literal['NFC', 'NFD', 'NFKC', 'NFKD']
     ]
+    """"""
 
 
 class VaultConfigServicesSettings(VaultConfigGlobalSettings, total=False):
@@ -81,14 +84,23 @@ class VaultConfigServicesSettings(VaultConfigGlobalSettings, total=False):
     """
 
     notes: NotRequired[str]
+    """"""
     length: NotRequired[int]
+    """"""
     repeat: NotRequired[int]
+    """"""
     lower: NotRequired[int]
+    """"""
     upper: NotRequired[int]
+    """"""
     number: NotRequired[int]
+    """"""
     space: NotRequired[int]
+    """"""
     dash: NotRequired[int]
+    """"""
     symbol: NotRequired[int]
+    """"""
 
 
 _VaultConfig = TypedDict(
@@ -99,7 +111,7 @@ class VaultConfigServicesSettings(VaultConfigGlobalSettings, total=False):
 
 
 class VaultConfig(TypedDict, _VaultConfig, total=False):
-    r"""Configuration for vault.
+    r"""Configuration for vault.  For typing purposes.
 
     Usually stored as JSON.
 
@@ -168,7 +180,9 @@ class KeyCommentPair(NamedTuple):
     """
 
     key: bytes | bytearray
+    """"""
     comment: bytes | bytearray
+    """"""
 
 
 class SSH_AGENTC(enum.Enum):  # noqa: N801
@@ -191,10 +205,15 @@ class SSH_AGENTC(enum.Enum):  # noqa: N801
     """
 
     REQUEST_IDENTITIES: int = 11
+    """"""
     SIGN_REQUEST: int = 13
+    """"""
     ADD_IDENTITY: int = 17
+    """"""
     REMOVE_IDENTITY: int = 18
+    """"""
     ADD_ID_CONSTRAINED: int = 25
+    """"""
 
 
 class SSH_AGENT(enum.Enum):  # noqa: N801
@@ -215,6 +234,10 @@ class SSH_AGENT(enum.Enum):  # noqa: N801
     """
 
     FAILURE: int = 5
+    """"""
     SUCCESS: int = 6
+    """"""
     IDENTITIES_ANSWER: int = 12
+    """"""
     SIGN_RESPONSE: int = 14
+    """"""
diff --git a/src/derivepassphrase/exporter/storeroom.py b/src/derivepassphrase/exporter/storeroom.py
index 24c5b4d..7769d1e 100644
--- a/src/derivepassphrase/exporter/storeroom.py
+++ b/src/derivepassphrase/exporter/storeroom.py
@@ -93,7 +93,9 @@ class KeyPair(TypedDict):
     """
 
     encryption_key: bytes
+    """"""
     signing_key: bytes
+    """"""
 
 
 class MasterKeys(TypedDict):
@@ -112,8 +114,11 @@ class MasterKeys(TypedDict):
     """
 
     hashing_key: bytes
+    """"""
     encryption_key: bytes
+    """"""
     signing_key: bytes
+    """"""
 
 
 def derive_master_keys_keys(password: str | bytes, iterations: int) -> KeyPair: