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.
- {doukimd-1.4.0 → doukimd-1.4.2}/PKG-INFO +3 -2
- {doukimd-1.4.0 → doukimd-1.4.2}/pyproject.toml +3 -2
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/__init__.py +1 -1
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/api.py +17 -4
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/build.py +21 -19
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/config.py +3 -3
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/content.py +11 -15
- doukimd-1.4.2/src/doukimd/indexes.py +222 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/markdown.py +20 -17
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/navigation.py +38 -42
- doukimd-1.4.2/src/doukimd/navigation_plan.py +531 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/notebook_rendering.py +7 -6
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/references.py +9 -17
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/runtime.py +3 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/theme.py +92 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/default/page.html +11 -8
- {doukimd-1.4.0 → doukimd-1.4.2}/LICENSE +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/README.md +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/__main__.py +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/assets.py +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/cli.py +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/collection.py +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/errors.py +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/html.py +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/models.py +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/notebook_models.py +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/notebooks.py +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/plugins.py +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/py.typed +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/search.py +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/default/palettes.json +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/default/search.js +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/default/theme.css +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/default/theme.js +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/vendor/bootstrap/LICENSE +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/vendor/bootstrap/README.md +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/vendor/bootstrap/bootstrap.min.css +0 -0
- {doukimd-1.4.0 → doukimd-1.4.2}/src/doukimd/themes/vendor/radix/LICENSE +0 -0
- {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.
|
|
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 (
|
|
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.
|
|
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
|
|
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",
|
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
196
|
-
if unquote(target.fragment) not in
|
|
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,
|
|
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,
|
|
334
|
-
validate_links(tokens, page,
|
|
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 =
|
|
366
|
-
navbar =
|
|
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 =
|
|
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:
|
|
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:
|
|
193
|
+
type: tuple[ApiSymbol, Ellipsis]
|
|
193
194
|
route:
|
|
194
195
|
type: str
|
|
195
|
-
|
|
196
|
-
type:
|
|
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
|
-
|
|
263
|
-
|
|
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',
|
|
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
|
-
|
|
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,
|
|
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
|
-
|
|
313
|
+
api,
|
|
309
314
|
)
|
|
310
|
-
selected = [
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
429
|
+
planned[identifier], posixpath.dirname(page.route) or '.'
|
|
427
430
|
),
|
|
428
431
|
)
|
|
429
432
|
label = Token('text', '', 0)
|
|
430
|
-
label.content =
|
|
433
|
+
label.content = api.symbols[identifier].name
|
|
431
434
|
children.extend([link, label, Token('link_close', 'a', -1)])
|
|
432
435
|
token.children = children
|