derivepassphrase.git

Enable cross-references on function signatures in documentation
Parent 1112627
Marco Ricci

Marco Ricci commited on 2024-09-29 23:17:02
Zeige 3 geänderte Dateien mit 30 Einfügungen und 3 Löschungen. 

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
Zeige Datei @ 7dbdf93
... ... 
@@ -73,11 +73,10 @@ plugins:
73 73 
           show_root_heading: true
74 74 
           show_symbol_type_heading: true
75 75 
           show_symbol_type_toc: true
76 
-          parameters_heading: true
77 76 
           members_order: 'source'
78 77 
           show_signature_annotations: true
79 78 
           separate_signature: true
80 
-          signature_crossrefs: false
79 
+          signature_crossrefs: true
81 80 
           unwrap_annotated: true
82 81 
         paths:
83 82 
           - src
src/derivepassphrase/_types.py
Zeige Datei @ 7dbdf93
... ... 
@@ -42,10 +42,13 @@ class VaultConfigGlobalSettings(TypedDict, total=False):
42 42 
     """
43 43
44 44 
     key: NotRequired[str]
45 
+    """"""
45 46 
     phrase: NotRequired[str]
47 
+    """"""
46 48 
     unicode_normalization_form: NotRequired[
47 49 
         Literal['NFC', 'NFD', 'NFKC', 'NFKD']
48 50 
     ]
51 
+    """"""
49 52
50 53
51 54 
 class VaultConfigServicesSettings(VaultConfigGlobalSettings, total=False):
... ... 
@@ -81,14 +84,23 @@ class VaultConfigServicesSettings(VaultConfigGlobalSettings, total=False):
81 84 
     """
82 85
83 86 
     notes: NotRequired[str]
87 
+    """"""
84 88 
     length: NotRequired[int]
89 
+    """"""
85 90 
     repeat: NotRequired[int]
91 
+    """"""
86 92 
     lower: NotRequired[int]
93 
+    """"""
87 94 
     upper: NotRequired[int]
95 
+    """"""
88 96 
     number: NotRequired[int]
97 
+    """"""
89 98 
     space: NotRequired[int]
99 
+    """"""
90 100 
     dash: NotRequired[int]
101 
+    """"""
91 102 
     symbol: NotRequired[int]
103 
+    """"""
92 104
93 105
94 106 
 _VaultConfig = TypedDict(
... ... 
@@ -99,7 +111,7 @@ _VaultConfig = TypedDict(
99 111
100 112
101 113 
 class VaultConfig(TypedDict, _VaultConfig, total=False):
102 
-    r"""Configuration for vault.
114 
+    r"""Configuration for vault.  For typing purposes.
103 115
104 116 
     Usually stored as JSON.
105 117
... ... 
@@ -168,7 +180,9 @@ class KeyCommentPair(NamedTuple):
168 180 
     """
169 181
170 182 
     key: bytes | bytearray
183 
+    """"""
171 184 
     comment: bytes | bytearray
185 
+    """"""
172 186
173 187
174 188 
 class SSH_AGENTC(enum.Enum):  # noqa: N801
... ... 
@@ -191,10 +205,15 @@ class SSH_AGENTC(enum.Enum):  # noqa: N801
191 205 
     """
192 206
193 207 
     REQUEST_IDENTITIES: int = 11
208 
+    """"""
194 209 
     SIGN_REQUEST: int = 13
210 
+    """"""
195 211 
     ADD_IDENTITY: int = 17
212 
+    """"""
196 213 
     REMOVE_IDENTITY: int = 18
214 
+    """"""
197 215 
     ADD_ID_CONSTRAINED: int = 25
216 
+    """"""
198 217
199 218
200 219 
 class SSH_AGENT(enum.Enum):  # noqa: N801
... ... 
@@ -215,6 +234,10 @@ class SSH_AGENT(enum.Enum):  # noqa: N801
215 234 
     """
216 235
217 236 
     FAILURE: int = 5
237 
+    """"""
218 238 
     SUCCESS: int = 6
239 
+    """"""
219 240 
     IDENTITIES_ANSWER: int = 12
241 
+    """"""
220 242 
     SIGN_RESPONSE: int = 14
243 
+    """"""
src/derivepassphrase/exporter/storeroom.py
Zeige Datei @ 7dbdf93
... ... 
@@ -93,7 +93,9 @@ class KeyPair(TypedDict):
93 93 
     """
94 94
95 95 
     encryption_key: bytes
96 
+    """"""
96 97 
     signing_key: bytes
98 
+    """"""
97 99
98 100
99 101 
 class MasterKeys(TypedDict):
... ... 
@@ -112,8 +114,11 @@ class MasterKeys(TypedDict):
112 114 
     """
113 115
114 116 
     hashing_key: bytes
117 
+    """"""
115 118 
     encryption_key: bytes
119 
+    """"""
116 120 
     signing_key: bytes
121 
+    """"""
117 122
118 123
119 124 
 def derive_master_keys_keys(password: str | bytes, iterations: int) -> KeyPair:
120 125