doukimd 1.4.0__tar.gz → 1.4.2__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.0 → doukimd-1.4.2}/PKG-INFO +3 -2
  2. {doukimd-1.4.0 → doukimd-1.4.2}/pyproject.toml +3 -2
  3. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/__init__.py +1 -1
  4. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/api.py +17 -4
  5. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/build.py +21 -19
  6. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/config.py +3 -3
  7. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/content.py +11 -15
  8. doukimd-1.4.2/src/doukimd/indexes.py +222 -0
  9. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/markdown.py +20 -17
  10. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/navigation.py +38 -42
  11. doukimd-1.4.2/src/doukimd/navigation_plan.py +531 -0
  12. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/notebook_rendering.py +7 -6
  13. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/references.py +9 -17
  14. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/runtime.py +3 -0
  15. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/theme.py +92 -0
  16. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/default/page.html +11 -8
  17. {doukimd-1.4.0 → doukimd-1.4.2}/LICENSE +0 -0
  18. {doukimd-1.4.0 → doukimd-1.4.2}/README.md +0 -0
  19. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/__main__.py +0 -0
  20. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/assets.py +0 -0
  21. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/cli.py +0 -0
  22. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/collection.py +0 -0
  23. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/errors.py +0 -0
  24. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/html.py +0 -0
  25. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/models.py +0 -0
  26. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/notebook_models.py +0 -0
  27. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/notebooks.py +0 -0
  28. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/plugins.py +0 -0
  29. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/py.typed +0 -0
  30. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/search.py +0 -0
  31. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/default/palettes.json +0 -0
  32. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/default/search.js +0 -0
  33. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/default/theme.css +0 -0
  34. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/default/theme.js +0 -0
  35. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/vendor/bootstrap/LICENSE +0 -0
  36. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/vendor/bootstrap/README.md +0 -0
  37. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/vendor/bootstrap/bootstrap.min.css +0 -0
  38. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/vendor/radix/LICENSE +0 -0
  39. {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/vendor/radix/README.md +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: doukimd
3
- Version: 1.4.0
3
+ Version: 1.4.2
4
4
  Summary: Markdown documentation with first-class Douki API references
5
5
  License-Expression: BSD-3-Clause
6
6
  License-File: LICENSE
@@ -14,11 +14,12 @@ Classifier: Programming Language :: Python :: 3.12
14
14
  Classifier: Programming Language :: Python :: 3.13
15
15
  Classifier: Programming Language :: Python :: 3.14
16
16
  Requires-Dist: Jinja2 (>=3.1.6,<4)
17
+ Requires-Dist: MarkupSafe (>=2.1,<4)
17
18
  Requires-Dist: PyYAML (>=6,<7)
18
19
  Requires-Dist: Pygments (>=2.18,<3)
19
20
  Requires-Dist: atpublic (>=5,<6)
20
21
  Requires-Dist: click (>=8.1,<9)
21
- Requires-Dist: douki (>=0.12.1,<0.13)
22
+ Requires-Dist: douki (==0.13.0)
22
23
  Requires-Dist: griffe (>=1.15,<2)
23
24
  Requires-Dist: jsonschema (>=4.23,<5)
24
25
  Requires-Dist: markdown-it-py (>=3,<5)
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "doukimd"
3
- version = "1.4.0" # semantic-release
3
+ version = "1.4.2" # 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"}]
@@ -9,11 +9,12 @@ requires-python = ">=3.10,<4"
9
9
  dependencies = [
10
10
  "atpublic>=5,<6",
11
11
  "click>=8.1,<9",
12
- "douki>=0.12.1,<0.13",
12
+ "douki==0.13.0",
13
13
  "griffe>=1.15,<2",
14
14
  "Jinja2>=3.1.6,<4",
15
15
  "jsonschema>=4.23,<5",
16
16
  "markdown-it-py>=3,<5",
17
+ "MarkupSafe>=2.1,<4",
17
18
  "mdit-py-plugins>=0.4,<0.7",
18
19
  "nbformat>=5.11,<6",
19
20
  "pluggy>=1.5,<2",
@@ -22,7 +22,7 @@ def get_version() -> str:
22
22
  try:
23
23
  return version('doukimd')
24
24
  except PackageNotFoundError:
25
- return '1.4.0' # semantic-release
25
+ return '1.4.2' # semantic-release
26
26
 
27
27
 
28
28
  __version__ = get_version()
@@ -7,6 +7,7 @@ from __future__ import annotations
7
7
  import json
8
8
  import re
9
9
 
10
+ from functools import lru_cache
10
11
  from importlib.resources import files
11
12
  from pathlib import Path
12
13
  from typing import cast
@@ -23,6 +24,21 @@ from doukimd.models import ApiSymbol, Config
23
24
  from doukimd.runtime import typechecked
24
25
 
25
26
 
27
+ @private
28
+ @lru_cache(maxsize=1)
29
+ @typechecked
30
+ def documentation_validator() -> Draft202012Validator:
31
+ """
32
+ title: Reuse the validator for the installed Douki schema.
33
+ returns:
34
+ type: Draft202012Validator
35
+ """
36
+ schema = json.loads(
37
+ files('douki').joinpath('schema.json').read_text(encoding='utf-8')
38
+ )
39
+ return Draft202012Validator(schema)
40
+
41
+
26
42
  @private
27
43
  @typechecked
28
44
  def source_path(node: griffe.Object) -> Path:
@@ -61,11 +77,8 @@ def documentation(node: griffe.Object, root: Path) -> dict[str, object]:
61
77
  'douki', f'Missing Douki docstring: {node.path}', path
62
78
  )
63
79
  data = read_yaml(node.docstring.value, path)
64
- schema = json.loads(
65
- files('douki').joinpath('schema.json').read_text(encoding='utf-8')
66
- )
67
80
  errors = sorted(
68
- Draft202012Validator(schema).iter_errors(data),
81
+ documentation_validator().iter_errors(data),
69
82
  key=lambda error: str(list(error.path)),
70
83
  )
71
84
  if errors:
@@ -38,6 +38,7 @@ from doukimd.content import (
38
38
  )
39
39
  from doukimd.errors import BuildError
40
40
  from doukimd.html import process_html
41
+ from doukimd.indexes import ApiIndex, SiteIndex
41
42
  from doukimd.markdown import (
42
43
  assign_anchors,
43
44
  markdown_parser,
@@ -45,16 +46,13 @@ from doukimd.markdown import (
45
46
  resolve_references,
46
47
  )
47
48
  from doukimd.models import Config, Page, SiteBuild
48
- from doukimd.navigation import (
49
- build_navbar,
50
- build_navigation,
51
- sidebar_for_page,
52
- )
49
+ from doukimd.navigation import sidebar_for_page
50
+ from doukimd.navigation_plan import NavigationPlan
53
51
  from doukimd.notebook_rendering import render_notebook
54
52
  from doukimd.plugins import plugin_context
55
53
  from doukimd.runtime import typechecked
56
54
  from doukimd.search import search_records
57
- from doukimd.theme import palette_colors, theme_assets
55
+ from doukimd.theme import NavigationFragments, palette_colors, theme_assets
58
56
 
59
57
  MANIFEST = '.doukimd-manifest.json'
60
58
 
@@ -143,7 +141,7 @@ def highlight_code(code: str, language: str, attrs: str) -> str:
143
141
  def validate_links(
144
142
  tokens: list[Token],
145
143
  page: Page,
146
- pages: dict[str, Page],
144
+ pages: SiteIndex | dict[str, Page],
147
145
  assets: dict[str, bytes],
148
146
  ) -> None:
149
147
  """
@@ -154,11 +152,13 @@ def validate_links(
154
152
  page:
155
153
  type: Page
156
154
  pages:
157
- type: dict[str, Page]
155
+ type: SiteIndex | dict[str, Page]
158
156
  assets:
159
157
  type: dict[str, bytes]
160
158
  """
161
159
 
160
+ planned = pages.by_route if isinstance(pages, SiteIndex) else pages
161
+
162
162
  @typechecked
163
163
  def resolve(value: str) -> str:
164
164
  """
@@ -188,12 +188,12 @@ def validate_links(
188
188
  if path
189
189
  else page.route
190
190
  )
191
- if route not in pages and route not in assets:
191
+ if route not in planned and route not in assets:
192
192
  raise BuildError(
193
193
  'references', f'Unknown local target: {value}', page.source
194
194
  )
195
- if target.fragment and route in pages:
196
- if unquote(target.fragment) not in pages[route].anchors:
195
+ if target.fragment and route in planned:
196
+ if unquote(target.fragment) not in planned[route].anchors:
197
197
  raise BuildError(
198
198
  'references',
199
199
  f'Unknown heading anchor: {value}',
@@ -277,6 +277,8 @@ def compile_site(config_path: Path) -> SiteBuild:
277
277
  page.source,
278
278
  )
279
279
  routes = plan_pages(pages, inventory, config)
280
+ api = ApiIndex(inventory, routes)
281
+ site = SiteIndex(pages)
280
282
  if not pages:
281
283
  raise BuildError('planning', 'The site has no pages')
282
284
  context: dict[str, object] = {
@@ -317,12 +319,10 @@ def compile_site(config_path: Path) -> SiteBuild:
317
319
  for page in pages:
318
320
  parser.options['html'] = page.settings.html
319
321
  if page.notebook is not None:
320
- tokens = render_notebook(
321
- page, root, config, context, parser, inventory
322
- )
322
+ tokens = render_notebook(page, root, config, context, parser, api)
323
323
  else:
324
324
  text = expand_page(page, root, config, context)
325
- tokens = parse_document(parser, text, page, inventory)
325
+ tokens = parse_document(parser, text, page, api)
326
326
  process_html(tokens, page)
327
327
  assign_anchors(tokens, page)
328
328
  documents[page.route] = tokens
@@ -330,8 +330,8 @@ def compile_site(config_path: Path) -> SiteBuild:
330
330
  by_route = {page.route: page for page in pages}
331
331
  for page in pages:
332
332
  tokens = documents[page.route]
333
- resolve_references(tokens, page, inventory, routes)
334
- validate_links(tokens, page, by_route, assets)
333
+ resolve_references(tokens, page, api, api)
334
+ validate_links(tokens, page, site, assets)
335
335
  loaders: list[BaseLoader] = [PackageLoader('doukimd', 'themes/default')]
336
336
  if config.theme.directory is not None:
337
337
  custom = project_path(root, config.theme.directory)
@@ -343,6 +343,7 @@ def compile_site(config_path: Path) -> SiteBuild:
343
343
  undefined=StrictUndefined,
344
344
  autoescape=True,
345
345
  )
346
+ environment.globals['navigation_fragment'] = NavigationFragments().render
346
347
  bundled = theme_assets(config.theme)
347
348
  if not config.search.enabled:
348
349
  bundled.pop('search.js')
@@ -356,14 +357,15 @@ def compile_site(config_path: Path) -> SiteBuild:
356
357
  MANIFEST,
357
358
  ]
358
359
  )
360
+ navigation = NavigationPlan(site, api, config)
359
361
  artifacts = {**assets, **bundled}
360
362
  search: list[dict[str, str]] = []
361
363
  for page in pages:
362
364
  tokens = documents[page.route]
363
365
  content = parser.renderer.render(tokens, parser.options, {})
364
366
  relative = posixpath.dirname(page.route) or '.'
365
- nav = build_navigation(pages, page, inventory, config)
366
- navbar = build_navbar(config, pages, page, inventory)
367
+ nav = navigation.navigation(page)
368
+ navbar = navigation.header(page)
367
369
  sidebar = sidebar_for_page(config, page)
368
370
  toc = [
369
371
  {
@@ -15,6 +15,8 @@ from doukimd.errors import BuildError
15
15
  from doukimd.models import Config
16
16
  from doukimd.runtime import typechecked
17
17
 
18
+ JSON_MAPPING = TypeAdapter(dict[str, JsonValue])
19
+
18
20
 
19
21
  @private
20
22
  class UniqueLoader(yaml.SafeLoader):
@@ -65,9 +67,7 @@ def read_yaml(text: str, source: Path) -> dict[str, object]:
65
67
  """
66
68
  try:
67
69
  raw = yaml.load(text, Loader=UniqueLoader)
68
- validated = TypeAdapter(dict[str, JsonValue]).validate_python(
69
- raw, strict=True
70
- )
70
+ validated = JSON_MAPPING.validate_python(raw, strict=True)
71
71
  return dict(validated)
72
72
  except (yaml.YAMLError, ValidationError) as error:
73
73
  raise BuildError('metadata', str(error), source) from error
@@ -24,6 +24,7 @@ from pydantic import ValidationError
24
24
 
25
25
  from doukimd.config import project_path, read_yaml
26
26
  from doukimd.errors import BuildError
27
+ from doukimd.indexes import ApiIndex
27
28
  from doukimd.models import ApiSymbol, Config, Page, PageSettings
28
29
  from doukimd.notebook_models import MarkdownCell
29
30
  from doukimd.notebooks import load_notebook, notebook_text
@@ -183,17 +184,17 @@ def api_route(identifier: str) -> str:
183
184
  @private
184
185
  @typechecked
185
186
  def api_summary(
186
- items: list[ApiSymbol], route: str, routes: dict[str, str]
187
+ items: tuple[ApiSymbol, ...], route: str, api: ApiIndex
187
188
  ) -> str:
188
189
  """
189
190
  title: Group links to immediate API children by declaration kind.
190
191
  parameters:
191
192
  items:
192
- type: list[ApiSymbol]
193
+ type: tuple[ApiSymbol, Ellipsis]
193
194
  route:
194
195
  type: str
195
- routes:
196
- type: dict[str, str]
196
+ api:
197
+ type: ApiIndex
197
198
  returns:
198
199
  type: str
199
200
  """
@@ -218,7 +219,7 @@ def api_summary(
218
219
  sections.append(f'## {title}')
219
220
  for item in members:
220
221
  target = posixpath.relpath(
221
- routes[item.identifier], posixpath.dirname(route)
222
+ api.routes[item.identifier], posixpath.dirname(route)
222
223
  )
223
224
  summary = ' '.join(
224
225
  str(item.documentation.get('title', '')).split()
@@ -259,14 +260,13 @@ def plan_pages(
259
260
  if counts[route.casefold()] > 1:
260
261
  suffix = hashlib.sha256(name.encode('utf-8')).hexdigest()[:16]
261
262
  routes[name] = route[:-5] + f'--{suffix}.html'
262
- roots = [
263
- item for item in inventory.values() if item.parent not in inventory
264
- ]
263
+ api = ApiIndex(inventory, routes)
264
+ roots = tuple(inventory[name] for name in api.roots.get(None, ()))
265
265
  pages.append(
266
266
  Page(
267
267
  'api/index.html',
268
268
  'API Docs',
269
- api_summary(roots, 'api/index.html', routes),
269
+ api_summary(roots, 'api/index.html', api),
270
270
  PageSettings(),
271
271
  )
272
272
  )
@@ -282,13 +282,9 @@ def plan_pages(
282
282
  ),
283
283
  f'::: api {identifier}\n:::\n\n'
284
284
  + api_summary(
285
- [
286
- child
287
- for child in inventory.values()
288
- if child.parent == identifier
289
- ],
285
+ api.children.get(identifier, ()),
290
286
  route,
291
- routes,
287
+ api,
292
288
  ),
293
289
  PageSettings(),
294
290
  symbol=identifier,
@@ -0,0 +1,222 @@
1
+ """
2
+ title: Validated immutable snapshots for one compilation.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+ from types import MappingProxyType
9
+ from typing import Mapping
10
+
11
+ from public import private
12
+
13
+ from doukimd.errors import BuildError
14
+ from doukimd.models import ApiSymbol, Page
15
+ from doukimd.runtime import typechecked
16
+
17
+
18
+ @private
19
+ @typechecked
20
+ @dataclass(frozen=True, init=False)
21
+ class ApiIndex:
22
+ """
23
+ title: >-
24
+ Validate symbol and route collections once and index their relations.
25
+ summary: Copies prevent callers from replacing entries after validation.
26
+ attributes:
27
+ symbols:
28
+ type: Mapping[str, ApiSymbol]
29
+ routes:
30
+ type: Mapping[str, str]
31
+ children:
32
+ type: Mapping[str | None, tuple[ApiSymbol, Ellipsis]]
33
+ roots:
34
+ type: Mapping[str | None, tuple[str, Ellipsis]]
35
+ exact_names:
36
+ type: Mapping[tuple[str | None, str], tuple[str, Ellipsis]]
37
+ canonical_names:
38
+ type: Mapping[tuple[str | None, str], tuple[str, Ellipsis]]
39
+ """
40
+
41
+ symbols: Mapping[str, ApiSymbol]
42
+ routes: Mapping[str, str]
43
+ children: Mapping[str | None, tuple[ApiSymbol, ...]]
44
+ roots: Mapping[str | None, tuple[str, ...]]
45
+ exact_names: Mapping[tuple[str | None, str], tuple[str, ...]]
46
+ canonical_names: Mapping[tuple[str | None, str], tuple[str, ...]]
47
+
48
+ def __init__(
49
+ self,
50
+ symbols: dict[str, ApiSymbol],
51
+ routes: dict[str, str] | None = None,
52
+ ) -> None:
53
+ """
54
+ title: >-
55
+ Capture checked inputs independently of their mutable containers.
56
+ parameters:
57
+ symbols:
58
+ type: dict[str, ApiSymbol]
59
+ routes:
60
+ type: dict[str, str] | None
61
+ """
62
+ captured = dict(symbols)
63
+ children: dict[str | None, list[ApiSymbol]] = {}
64
+ roots: dict[str | None, list[str]] = {}
65
+ exact: dict[tuple[str | None, str], list[str]] = {}
66
+ canonical: dict[tuple[str | None, str], list[str]] = {}
67
+ for name, item in captured.items():
68
+ children.setdefault(item.parent, []).append(item)
69
+ for source in {None, item.source_name}:
70
+ key = (source, name.rsplit(':', 1)[-1])
71
+ exact.setdefault(key, []).append(name)
72
+ if item.canonical is not None:
73
+ key = (source, item.canonical.rsplit(':', 1)[-1])
74
+ canonical.setdefault(key, []).append(name)
75
+ if item.parent not in captured:
76
+ roots.setdefault(source, []).append(name)
77
+ object.__setattr__(self, 'symbols', MappingProxyType(captured))
78
+ object.__setattr__(
79
+ self, 'routes', MappingProxyType(dict(routes or {}))
80
+ )
81
+ object.__setattr__(
82
+ self,
83
+ 'children',
84
+ MappingProxyType(
85
+ {key: tuple(value) for key, value in children.items()}
86
+ ),
87
+ )
88
+ object.__setattr__(
89
+ self,
90
+ 'roots',
91
+ MappingProxyType(
92
+ {key: tuple(value) for key, value in roots.items()}
93
+ ),
94
+ )
95
+ object.__setattr__(
96
+ self,
97
+ 'exact_names',
98
+ MappingProxyType(
99
+ {key: tuple(value) for key, value in exact.items()}
100
+ ),
101
+ )
102
+ object.__setattr__(
103
+ self,
104
+ 'canonical_names',
105
+ MappingProxyType(
106
+ {key: tuple(value) for key, value in canonical.items()}
107
+ ),
108
+ )
109
+
110
+ def ancestors(self, identifier: str) -> tuple[ApiSymbol, ...]:
111
+ """
112
+ title: Follow one symbol's ancestry without traversing unrelated APIs.
113
+ parameters:
114
+ identifier:
115
+ type: str
116
+ returns:
117
+ type: tuple[ApiSymbol, Ellipsis]
118
+ """
119
+ result: list[ApiSymbol] = []
120
+ seen: set[str] = set()
121
+ while identifier in self.symbols:
122
+ if identifier in seen:
123
+ raise BuildError('api', f'Cyclic API parent: {identifier}')
124
+ seen.add(identifier)
125
+ item = self.symbols[identifier]
126
+ result.append(item)
127
+ if item.parent is None:
128
+ break
129
+ identifier = item.parent
130
+ return tuple(result)
131
+
132
+
133
+ @private
134
+ @typechecked
135
+ @dataclass(frozen=True, init=False)
136
+ class SiteIndex:
137
+ """
138
+ title: >-
139
+ Snapshot planned page membership while anchors are populated in place.
140
+ attributes:
141
+ pages:
142
+ type: tuple[Page, Ellipsis]
143
+ by_route:
144
+ type: Mapping[str, Page]
145
+ by_symbol:
146
+ type: Mapping[str, Page]
147
+ api_page:
148
+ type: Page | None
149
+ """
150
+
151
+ pages: tuple[Page, ...]
152
+ by_route: Mapping[str, Page]
153
+ by_symbol: Mapping[str, Page]
154
+ api_page: Page | None
155
+
156
+ def __init__(self, pages: list[Page]) -> None:
157
+ """
158
+ title: Capture checked pages after route planning has completed.
159
+ parameters:
160
+ pages:
161
+ type: list[Page]
162
+ """
163
+ captured = tuple(pages)
164
+ object.__setattr__(self, 'pages', captured)
165
+ object.__setattr__(
166
+ self,
167
+ 'by_route',
168
+ MappingProxyType({page.route: page for page in captured}),
169
+ )
170
+ object.__setattr__(
171
+ self,
172
+ 'by_symbol',
173
+ MappingProxyType(
174
+ {
175
+ page.symbol: page
176
+ for page in captured
177
+ if page.symbol is not None
178
+ }
179
+ ),
180
+ )
181
+ object.__setattr__(
182
+ self,
183
+ 'api_page',
184
+ next(
185
+ (
186
+ page
187
+ for page in captured
188
+ if page.route == 'api/index.html' and page.source is None
189
+ ),
190
+ None,
191
+ ),
192
+ )
193
+
194
+
195
+ @private
196
+ @typechecked
197
+ def api_index(inventory: ApiIndex | dict[str, ApiSymbol]) -> ApiIndex:
198
+ """
199
+ title: Reuse a snapshot or validate a standalone helper's dictionary input.
200
+ parameters:
201
+ inventory:
202
+ type: ApiIndex | dict[str, ApiSymbol]
203
+ returns:
204
+ type: ApiIndex
205
+ """
206
+ return (
207
+ inventory if isinstance(inventory, ApiIndex) else ApiIndex(inventory)
208
+ )
209
+
210
+
211
+ @private
212
+ @typechecked
213
+ def site_index(pages: SiteIndex | list[Page]) -> SiteIndex:
214
+ """
215
+ title: Reuse a snapshot or validate a standalone helper's page list.
216
+ parameters:
217
+ pages:
218
+ type: SiteIndex | list[Page]
219
+ returns:
220
+ type: SiteIndex
221
+ """
222
+ return pages if isinstance(pages, SiteIndex) else SiteIndex(pages)
@@ -23,6 +23,7 @@ from pydantic import ValidationError
23
23
  from doukimd.config import read_yaml
24
24
  from doukimd.content import md_text
25
25
  from doukimd.errors import BuildError
26
+ from doukimd.indexes import ApiIndex, api_index
26
27
  from doukimd.models import ApiSymbol, Page, Settings
27
28
  from doukimd.references import resolve_symbol
28
29
  from doukimd.runtime import typechecked
@@ -279,7 +280,10 @@ def field_description(value: object) -> str:
279
280
  @public
280
281
  @typechecked
281
282
  def parse_document(
282
- parser: MarkdownIt, text: str, page: Page, inventory: dict[str, ApiSymbol]
283
+ parser: MarkdownIt,
284
+ text: str,
285
+ page: Page,
286
+ inventory: ApiIndex | dict[str, ApiSymbol],
283
287
  ) -> list[Token]:
284
288
  """
285
289
  title: Expand API nodes into ordinary document tokens before resolution.
@@ -291,10 +295,11 @@ def parse_document(
291
295
  page:
292
296
  type: Page
293
297
  inventory:
294
- type: dict[str, ApiSymbol]
298
+ type: ApiIndex | dict[str, ApiSymbol]
295
299
  returns:
296
300
  type: list[Token]
297
301
  """
302
+ api = api_index(inventory)
298
303
  try:
299
304
  tokens = parser.parse(text)
300
305
  expanded: list[Token] = []
@@ -305,15 +310,11 @@ def parse_document(
305
310
  identifier = resolve_symbol(
306
311
  str(token.meta['identifier']),
307
312
  token.meta.get('source') or page.settings.api_source,
308
- inventory,
313
+ api,
309
314
  )
310
- selected = [inventory[identifier]]
315
+ selected = [api.symbols[identifier]]
311
316
  if token.meta['members'] == 'public':
312
- selected.extend(
313
- item
314
- for item in inventory.values()
315
- if item.parent == identifier
316
- )
317
+ selected.extend(api.children.get(identifier, ()))
317
318
  for item in selected:
318
319
  content = api_markdown(item, bool(token.meta['show_source']))
319
320
  # Authored HTML settings do not apply to docstrings.
@@ -378,8 +379,8 @@ def assign_anchors(tokens: list[Token], page: Page) -> None:
378
379
  def resolve_references(
379
380
  tokens: list[Token],
380
381
  page: Page,
381
- inventory: dict[str, ApiSymbol],
382
- routes: dict[str, str],
382
+ inventory: ApiIndex | dict[str, ApiSymbol],
383
+ routes: ApiIndex | dict[str, str],
383
384
  ) -> None:
384
385
  """
385
386
  title: Resolve forward API references using the complete site inventory.
@@ -389,10 +390,12 @@ def resolve_references(
389
390
  page:
390
391
  type: Page
391
392
  inventory:
392
- type: dict[str, ApiSymbol]
393
+ type: ApiIndex | dict[str, ApiSymbol]
393
394
  routes:
394
- type: dict[str, str]
395
+ type: ApiIndex | dict[str, str]
395
396
  """
397
+ api = api_index(inventory)
398
+ planned = routes.routes if isinstance(routes, ApiIndex) else routes
396
399
  for token in tokens:
397
400
  if token.children is None:
398
401
  continue
@@ -405,7 +408,7 @@ def resolve_references(
405
408
  identifier = resolve_symbol(
406
409
  str(child.meta['identifier']),
407
410
  child.meta.get('source') or page.settings.api_source,
408
- inventory,
411
+ api,
409
412
  )
410
413
  except BuildError as error:
411
414
  raise BuildError(
@@ -413,7 +416,7 @@ def resolve_references(
413
416
  f'No generated API page: {error.message}',
414
417
  page.source,
415
418
  ) from error
416
- if identifier not in routes:
419
+ if identifier not in planned:
417
420
  raise BuildError(
418
421
  'references',
419
422
  f'No generated API page for {identifier}',
@@ -423,10 +426,10 @@ def resolve_references(
423
426
  link.attrSet(
424
427
  'href',
425
428
  posixpath.relpath(
426
- routes[identifier], posixpath.dirname(page.route) or '.'
429
+ planned[identifier], posixpath.dirname(page.route) or '.'
427
430
  ),
428
431
  )
429
432
  label = Token('text', '', 0)
430
- label.content = inventory[identifier].name
433
+ label.content = api.symbols[identifier].name
431
434
  children.extend([link, label, Token('link_close', 'a', -1)])
432
435
  token.children = children