doukimd 1.4.2__tar.gz → 1.4.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. {doukimd-1.4.2 → doukimd-1.4.3}/PKG-INFO +8 -4
  2. {doukimd-1.4.2 → doukimd-1.4.3}/README.md +5 -0
  3. {doukimd-1.4.2 → doukimd-1.4.3}/pyproject.toml +3 -3
  4. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/__init__.py +2 -2
  5. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/api.py +127 -24
  6. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/assets.py +7 -7
  7. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/build.py +18 -18
  8. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/cli.py +2 -2
  9. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/collection.py +61 -48
  10. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/config.py +14 -14
  11. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/content.py +28 -28
  12. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/errors.py +6 -6
  13. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/html.py +20 -19
  14. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/indexes.py +29 -26
  15. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/markdown.py +32 -32
  16. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/models.py +96 -91
  17. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/navigation.py +44 -44
  18. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/navigation_plan.py +83 -70
  19. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/notebook_models.py +26 -26
  20. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/notebook_rendering.py +48 -47
  21. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/notebooks.py +4 -4
  22. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/plugins.py +5 -4
  23. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/references.py +4 -4
  24. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/runtime.py +7 -5
  25. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/search.py +13 -13
  26. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/theme.py +25 -17
  27. {doukimd-1.4.2 → doukimd-1.4.3}/LICENSE +0 -0
  28. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/__main__.py +0 -0
  29. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/py.typed +0 -0
  30. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/themes/default/page.html +0 -0
  31. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/themes/default/palettes.json +0 -0
  32. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/themes/default/search.js +0 -0
  33. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/themes/default/theme.css +0 -0
  34. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/themes/default/theme.js +0 -0
  35. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/themes/vendor/bootstrap/LICENSE +0 -0
  36. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/themes/vendor/bootstrap/README.md +0 -0
  37. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/themes/vendor/bootstrap/bootstrap.min.css +0 -0
  38. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/themes/vendor/radix/LICENSE +0 -0
  39. {doukimd-1.4.2 → doukimd-1.4.3}/src/doukimd/themes/vendor/radix/README.md +0 -0
@@ -1,14 +1,13 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: doukimd
3
- Version: 1.4.2
3
+ Version: 1.4.3
4
4
  Summary: Markdown documentation with first-class Douki API references
5
5
  License-Expression: BSD-3-Clause
6
6
  License-File: LICENSE
7
7
  Author: Ivan Ogasawara
8
8
  Author-email: ivan.ogasawara@gmail.com
9
- Requires-Python: >=3.10,<4
9
+ Requires-Python: >=3.11,<4
10
10
  Classifier: Programming Language :: Python :: 3
11
- Classifier: Programming Language :: Python :: 3.10
12
11
  Classifier: Programming Language :: Python :: 3.11
13
12
  Classifier: Programming Language :: Python :: 3.12
14
13
  Classifier: Programming Language :: Python :: 3.13
@@ -19,7 +18,7 @@ Requires-Dist: PyYAML (>=6,<7)
19
18
  Requires-Dist: Pygments (>=2.18,<3)
20
19
  Requires-Dist: atpublic (>=5,<6)
21
20
  Requires-Dist: click (>=8.1,<9)
22
- Requires-Dist: douki (==0.13.0)
21
+ Requires-Dist: douki (>=0.14.0)
23
22
  Requires-Dist: griffe (>=1.15,<2)
24
23
  Requires-Dist: jsonschema (>=4.23,<5)
25
24
  Requires-Dist: markdown-it-py (>=3,<5)
@@ -41,7 +40,12 @@ Douki YAML docstrings. This initial version supports Python projects.
41
40
 
42
41
  ## Run from source
43
42
 
43
+ Use Python 3.10–3.14 and install
44
+ [Poetry separately](https://python-poetry.org/docs/#installation) from the
45
+ project environment.
46
+
44
47
  ```console
48
+ poetry env use python3.14
45
49
  poetry install
46
50
  poetry run doukimd build --config examples/basic/doukimd.yaml
47
51
  ```
@@ -8,7 +8,12 @@ Douki YAML docstrings. This initial version supports Python projects.
8
8
 
9
9
  ## Run from source
10
10
 
11
+ Use Python 3.10–3.14 and install
12
+ [Poetry separately](https://python-poetry.org/docs/#installation) from the
13
+ project environment.
14
+
11
15
  ```console
16
+ poetry env use python3.14
12
17
  poetry install
13
18
  poetry run doukimd build --config examples/basic/doukimd.yaml
14
19
  ```
@@ -1,15 +1,15 @@
1
1
  [project]
2
2
  name = "doukimd"
3
- version = "1.4.2" # semantic-release
3
+ version = "1.4.3" # semantic-release
4
4
  description = "Markdown documentation with first-class Douki API references"
5
5
  readme = "README.md"
6
6
  authors = [{name = "Ivan Ogasawara", email = "ivan.ogasawara@gmail.com"}]
7
7
  license = "BSD-3-Clause"
8
- requires-python = ">=3.10,<4"
8
+ requires-python = ">=3.11,<4"
9
9
  dependencies = [
10
10
  "atpublic>=5,<6",
11
11
  "click>=8.1,<9",
12
- "douki==0.13.0",
12
+ "douki>=0.14.0",
13
13
  "griffe>=1.15,<2",
14
14
  "Jinja2>=3.1.6,<4",
15
15
  "jsonschema>=4.23,<5",
@@ -17,12 +17,12 @@ def get_version() -> str:
17
17
  """
18
18
  title: Return the installed version or the source-tree fallback.
19
19
  returns:
20
- type: str
20
+ description: Installed package version or the source fallback.
21
21
  """
22
22
  try:
23
23
  return version('doukimd')
24
24
  except PackageNotFoundError:
25
- return '1.4.2' # semantic-release
25
+ return '1.4.3' # semantic-release
26
26
 
27
27
 
28
28
  __version__ = get_version()
@@ -10,10 +10,12 @@ import re
10
10
  from functools import lru_cache
11
11
  from importlib.resources import files
12
12
  from pathlib import Path
13
- from typing import cast
13
+ from typing import Literal, cast
14
14
 
15
15
  import griffe
16
16
 
17
+ from douki import DocumentationError, Parameter, enrich
18
+ from douki import Signature as DocumentationSignature
17
19
  from jsonschema import Draft202012Validator
18
20
  from plum import dispatch
19
21
  from public import private, public
@@ -31,7 +33,7 @@ def documentation_validator() -> Draft202012Validator:
31
33
  """
32
34
  title: Reuse the validator for the installed Douki schema.
33
35
  returns:
34
- type: Draft202012Validator
36
+ description: Cached validator for the installed schema.
35
37
  """
36
38
  schema = json.loads(
37
39
  files('douki').joinpath('schema.json').read_text(encoding='utf-8')
@@ -46,9 +48,9 @@ def source_path(node: griffe.Object) -> Path:
46
48
  title: Reject namespace packages without a single source file.
47
49
  parameters:
48
50
  node:
49
- type: griffe.Object
51
+ description: Source declaration or parsed document node to process.
50
52
  returns:
51
- type: Path
53
+ description: Resolved path to the declaration source file.
52
54
  """
53
55
  path = node.filepath
54
56
  if not isinstance(path, Path):
@@ -56,6 +58,104 @@ def source_path(node: griffe.Object) -> Path:
56
58
  return path.resolve()
57
59
 
58
60
 
61
+ @private
62
+ @dispatch
63
+ @typechecked
64
+ def annotation_signature(node: object) -> DocumentationSignature:
65
+ """
66
+ title: Reject unsupported static annotation adapters.
67
+ parameters:
68
+ node: Declaration whose annotation metadata is requested.
69
+ returns: Static metadata accepted by Douki's public enrichment API.
70
+ """
71
+ raise BuildError('api', f'Unsupported declaration: {type(node).__name__}')
72
+
73
+
74
+ @dispatch
75
+ @typechecked
76
+ def annotation_signature(
77
+ node: griffe.Module | griffe.Attribute,
78
+ ) -> DocumentationSignature:
79
+ """
80
+ title: Retain property return annotations without inspecting values.
81
+ parameters:
82
+ node: Module or data declaration being documented.
83
+ returns: Property return annotation or empty non-callable metadata.
84
+ """
85
+ if isinstance(node, griffe.Attribute) and 'property' in node.labels:
86
+ return DocumentationSignature(
87
+ parameters=(),
88
+ returns=str(node.annotation)
89
+ if node.annotation is not None
90
+ else '',
91
+ )
92
+ return DocumentationSignature()
93
+
94
+
95
+ @dispatch
96
+ @typechecked
97
+ def annotation_signature(node: griffe.Class) -> DocumentationSignature:
98
+ """
99
+ title: Supply class field annotations without evaluating their values.
100
+ parameters:
101
+ node: Class whose locally declared attributes are being documented.
102
+ returns: Annotated fields available for documentation enrichment.
103
+ """
104
+ return DocumentationSignature(
105
+ attributes=tuple(
106
+ Parameter(name, str(member.annotation))
107
+ for name, member in node.members.items()
108
+ if isinstance(member, griffe.Attribute)
109
+ and member.annotation is not None
110
+ )
111
+ )
112
+
113
+
114
+ @dispatch
115
+ @typechecked
116
+ def annotation_signature(node: griffe.Function) -> DocumentationSignature:
117
+ """
118
+ title: Adapt static callable annotations and variadic parameter kinds.
119
+ parameters:
120
+ node: Callable declaration, including one dispatch or overload variant.
121
+ returns: Explicit parameters and return annotation for Douki enrichment.
122
+ """
123
+ kinds: dict[
124
+ griffe.ParameterKind,
125
+ Literal[
126
+ 'regular',
127
+ 'positional_only',
128
+ 'keyword_only',
129
+ 'var_positional',
130
+ 'var_keyword',
131
+ ],
132
+ ] = {
133
+ griffe.ParameterKind.positional_only: 'positional_only',
134
+ griffe.ParameterKind.positional_or_keyword: 'regular',
135
+ griffe.ParameterKind.keyword_only: 'keyword_only',
136
+ griffe.ParameterKind.var_positional: 'var_positional',
137
+ griffe.ParameterKind.var_keyword: 'var_keyword',
138
+ }
139
+ return DocumentationSignature(
140
+ parameters=tuple(
141
+ Parameter(
142
+ parameter.name,
143
+ str(parameter.annotation)
144
+ if parameter.annotation is not None
145
+ else '',
146
+ kinds[parameter.kind],
147
+ )
148
+ for parameter in node.parameters
149
+ if not (
150
+ isinstance(node.parent, griffe.Class)
151
+ and 'staticmethod' not in node.labels
152
+ and parameter.name in {'self', 'cls'}
153
+ )
154
+ ),
155
+ returns=str(node.returns) if node.returns is not None else '',
156
+ )
157
+
158
+
59
159
  @private
60
160
  @typechecked
61
161
  def documentation(node: griffe.Object, root: Path) -> dict[str, object]:
@@ -63,11 +163,11 @@ def documentation(node: griffe.Object, root: Path) -> dict[str, object]:
63
163
  title: Validate a source docstring using the installed Douki schema.
64
164
  parameters:
65
165
  node:
66
- type: griffe.Object
166
+ description: Source declaration or parsed document node to process.
67
167
  root:
68
- type: Path
168
+ description: Project root used to resolve relative paths.
69
169
  returns:
70
- type: dict[str, object]
170
+ description: Validated documentation fields from the source.
71
171
  """
72
172
  path = source_path(node)
73
173
  if not path.is_relative_to(root):
@@ -105,7 +205,10 @@ def documentation(node: griffe.Object, root: Path) -> dict[str, object]:
105
205
  f'{node.path}: documented parameters do not match signature',
106
206
  path,
107
207
  )
108
- return data
208
+ try:
209
+ return enrich(node.docstring.value, annotation_signature(node))
210
+ except DocumentationError as error:
211
+ raise BuildError('douki', f'{node.path}: {error}', path) from error
109
212
 
110
213
 
111
214
  @private
@@ -116,9 +219,9 @@ def signature(node: object) -> str:
116
219
  title: Reject unsupported API declarations.
117
220
  parameters:
118
221
  node:
119
- type: object
222
+ description: Source declaration or parsed document node to process.
120
223
  returns:
121
- type: str
224
+ description: Display signature preserving source annotations.
122
225
  """
123
226
  raise BuildError('api', f'Unsupported declaration: {type(node).__name__}')
124
227
 
@@ -130,9 +233,9 @@ def signature(node: griffe.Module) -> str:
130
233
  title: Display a module name.
131
234
  parameters:
132
235
  node:
133
- type: griffe.Module
236
+ description: Source declaration or parsed document node to process.
134
237
  returns:
135
- type: str
238
+ description: Display signature preserving source annotations.
136
239
  """
137
240
  return node.path
138
241
 
@@ -144,9 +247,9 @@ def signature(node: griffe.Class | griffe.Function) -> str:
144
247
  title: Preserve the source signature through Griffe.
145
248
  parameters:
146
249
  node:
147
- type: griffe.Class | griffe.Function
250
+ description: Source declaration or parsed document node to process.
148
251
  returns:
149
- type: str
252
+ description: Display signature preserving source annotations.
150
253
  """
151
254
  return node.signature()
152
255
 
@@ -158,9 +261,9 @@ def signature(node: griffe.Attribute) -> str:
158
261
  title: Display a data declaration without evaluating its value.
159
262
  parameters:
160
263
  node:
161
- type: griffe.Attribute
264
+ description: Source declaration or parsed document node to process.
162
265
  returns:
163
- type: str
266
+ description: Display signature preserving source annotations.
164
267
  """
165
268
  annotation = f': {node.annotation}' if node.annotation else ''
166
269
  value = f' = {node.value}' if node.value is not None else ''
@@ -174,9 +277,9 @@ def hidden(node: griffe.Object) -> bool:
174
277
  title: Honor explicit visibility rather than underscore naming heuristics.
175
278
  parameters:
176
279
  node:
177
- type: griffe.Object
280
+ description: Source declaration or parsed document node to process.
178
281
  returns:
179
- type: bool
282
+ description: Whether explicit metadata marks the declaration as private.
180
283
  """
181
284
  for decorator in getattr(node, 'decorators', []):
182
285
  name = str(decorator.value).split('(', maxsplit=1)[0]
@@ -199,11 +302,11 @@ def visit(node: object, root: Path) -> list[ApiSymbol]:
199
302
  title: Visit a declaration using the default unscoped collector.
200
303
  parameters:
201
304
  node:
202
- type: object
305
+ description: Source declaration or parsed document node to process.
203
306
  root:
204
- type: Path
307
+ description: Project root used to resolve relative paths.
205
308
  returns:
206
- type: list[ApiSymbol]
309
+ description: Processed declarations or document tokens.
207
310
  """
208
311
  from doukimd.collection import Collector, FunctionCapture
209
312
 
@@ -222,11 +325,11 @@ def collect_api(root: Path, config: Config) -> dict[str, ApiSymbol]:
222
325
  title: Collect isolated source folders without importing project code.
223
326
  parameters:
224
327
  root:
225
- type: Path
328
+ description: Project root used to resolve relative paths.
226
329
  config:
227
- type: Config
330
+ description: Validated project settings or their configuration file.
228
331
  returns:
229
- type: dict[str, ApiSymbol]
332
+ description: Collected declarations keyed by stable API identity.
230
333
  """
231
334
  from doukimd.collection import Collector, FunctionCapture
232
335
 
@@ -24,11 +24,11 @@ def copy_assets(root: Path, config: Config) -> dict[str, bytes]:
24
24
  title: Copy matched docs-relative files and reject unsafe patterns.
25
25
  parameters:
26
26
  root:
27
- type: Path
27
+ description: Project root used to resolve relative paths.
28
28
  config:
29
- type: Config
29
+ description: Validated project settings or their configuration file.
30
30
  returns:
31
- type: dict[str, bytes]
31
+ description: Output destinations mapped to their asset bytes.
32
32
  """
33
33
  docs = project_path(root, config.docs_dir)
34
34
  result: dict[str, bytes] = {}
@@ -75,13 +75,13 @@ def asset_url(
75
75
  title: Resolve a configured docs-root asset relative to a planned page.
76
76
  parameters:
77
77
  value:
78
- type: str | None
78
+ description: Input value to validate or render.
79
79
  route:
80
- type: str
80
+ description: Planned output path relative to the site root.
81
81
  assets:
82
- type: dict[str, bytes]
82
+ description: Asset destinations and bytes included in the build.
83
83
  returns:
84
- type: str | None
84
+ description: Validated asset link relative to the current page.
85
85
  """
86
86
  if value is None:
87
87
  return None
@@ -64,11 +64,11 @@ def output_path(root: Path, config: Config) -> Path:
64
64
  title: Reject output paths that overlap any project input.
65
65
  parameters:
66
66
  root:
67
- type: Path
67
+ description: Project root used to resolve relative paths.
68
68
  config:
69
- type: Config
69
+ description: Validated project settings or their configuration file.
70
70
  returns:
71
- type: Path
71
+ description: Resolved output directory confined to the project.
72
72
  """
73
73
  output = project_path(root, config.output_dir)
74
74
  protected = [
@@ -119,13 +119,13 @@ def highlight_code(code: str, language: str, attrs: str) -> str:
119
119
  title: Highlight code with a plain-text fallback for unknown languages.
120
120
  parameters:
121
121
  code:
122
- type: str
122
+ description: Source code to highlight.
123
123
  language:
124
- type: str
124
+ description: Source language used for highlighting or collection.
125
125
  attrs:
126
- type: str
126
+ description: Attributes attached to the generated element.
127
127
  returns:
128
- type: str
128
+ description: Highlighted code or escaped plain text.
129
129
  """
130
130
  del attrs
131
131
  try:
@@ -148,13 +148,13 @@ def validate_links(
148
148
  title: Rewrite Markdown links and validate local files and anchors.
149
149
  parameters:
150
150
  tokens:
151
- type: list[Token]
151
+ description: Parsed document tokens in rendering order.
152
152
  page:
153
- type: Page
153
+ description: Page being compiled or used to resolve links.
154
154
  pages:
155
- type: SiteIndex | dict[str, Page]
155
+ description: Pages with their planned output routes.
156
156
  assets:
157
- type: dict[str, bytes]
157
+ description: Asset destinations and bytes included in the build.
158
158
  """
159
159
 
160
160
  planned = pages.by_route if isinstance(pages, SiteIndex) else pages
@@ -165,9 +165,9 @@ def validate_links(
165
165
  title: Validate and rewrite one Markdown or authored HTML URL.
166
166
  parameters:
167
167
  value:
168
- type: str
168
+ description: Input value to validate or render.
169
169
  returns:
170
- type: str
170
+ description: Validated link rewritten for the current output page.
171
171
  """
172
172
  try:
173
173
  target = urlsplit(value)
@@ -234,7 +234,7 @@ def check_output_routes(routes: list[str]) -> None:
234
234
  title: Reject case-insensitive file and directory collisions before output.
235
235
  parameters:
236
236
  routes:
237
- type: list[str]
237
+ description: Planned output routes used to validate destinations.
238
238
  """
239
239
  seen: set[str] = set()
240
240
  for route in routes:
@@ -255,9 +255,9 @@ def compile_site(config_path: Path) -> SiteBuild:
255
255
  title: Compile all pages and references without writing output.
256
256
  parameters:
257
257
  config_path:
258
- type: Path
258
+ description: Path to the project configuration file.
259
259
  returns:
260
- type: SiteBuild
260
+ description: Complete generated files and page count.
261
261
  """
262
262
  config_path = config_path.resolve()
263
263
  root = config_path.parent
@@ -480,9 +480,9 @@ def build_site(config_path: Path) -> SiteBuild:
480
480
  title: Replace managed output only after the entire build succeeds.
481
481
  parameters:
482
482
  config_path:
483
- type: Path
483
+ description: Path to the project configuration file.
484
484
  returns:
485
- type: SiteBuild
485
+ description: Successfully published files and page count.
486
486
  """
487
487
  config_path = config_path.resolve()
488
488
  result = compile_site(config_path)
@@ -41,7 +41,7 @@ def build(config_path: Path) -> None:
41
41
  title: Build a static HTML documentation site.
42
42
  parameters:
43
43
  config_path:
44
- type: Path
44
+ description: Path to the project configuration file.
45
45
  """
46
46
  try:
47
47
  result = build_site(config_path)
@@ -65,7 +65,7 @@ def check(config_path: Path) -> None:
65
65
  title: Validate a complete site without writing output.
66
66
  parameters:
67
67
  config_path:
68
- type: Path
68
+ description: Path to the project configuration file.
69
69
  """
70
70
  try:
71
71
  result = compile_site(config_path)