doukimd 1.0.0__tar.gz

doukimd-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, ARX
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

doukimd-1.0.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: doukimd
+Version: 1.0.0
+Summary: Markdown documentation with first-class Douki API references
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Author: Ivan Ogasawara
+Author-email: ivan.ogasawara@gmail.com
+Requires-Python: >=3.10,<4
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: Jinja2 (>=3.1.6,<4)
+Requires-Dist: PyYAML (>=6,<7)
+Requires-Dist: Pygments (>=2.18,<3)
+Requires-Dist: atpublic (>=5,<6)
+Requires-Dist: click (>=8.1,<9)
+Requires-Dist: douki (>=0.12.1,<0.13)
+Requires-Dist: griffe (>=1.15,<2)
+Requires-Dist: jsonschema (>=4.23,<5)
+Requires-Dist: markdown-it-py (>=3,<5)
+Requires-Dist: mdit-py-plugins (>=0.4,<0.7)
+Requires-Dist: pluggy (>=1.5,<2)
+Requires-Dist: plum-dispatch (>=2.5,<3)
+Requires-Dist: pydantic (>=2.10,<3)
+Requires-Dist: typeguard (>=4.4,<5)
+Description-Content-Type: text/markdown
+
+# DoukiMD
+
+Markdown documentation with first-class
+[Douki](https://github.com/arxlang/douki) API references.
+
+DoukiMD is an opinionated static documentation engine for projects using
+Douki YAML docstrings. This initial version supports Python projects.
+
+## Run from source
+
+```console
+poetry install
+poetry run doukimd build --config examples/basic/doukimd.yaml
+```
+
+Open `examples/basic/build/index.html` to view the generated site.
+Use `doukimd check` to validate without writing files.
+
+## Included
+
+- Markdown pages with validated YAML front matter.
+- Opt-in Jinja in Markdown with project, page, data, and API metadata.
+- Static Python API extraction and validation against Douki's shipped schema.
+- Public re-exports, properties, data declarations, and callable variants.
+- Named API source folders with per-page and per-block selection.
+- Native API blocks, virtual API pages, and forward API references.
+- Ordered navbar menus and product sidebars with source-scoped API trees.
+- Page layouts, trusted HTML opt-in, local branding, and extra stylesheets.
+- Local link and heading validation, assets, code highlighting, and JSON
+  symbol and search inventories.
+- A bundled theme, local Jinja theme overrides, and explicit context plugins.
+- Safe replacement of managed output after successful builds.
+
+See [authoring and configuration](docs/usage.md) and the complete
+[example project](examples/basic).
+
+## Initial scope
+
+Python 3.10–3.14 is supported. Handwritten modules, classes, and callables
+require valid Douki docstrings. Data declarations can use their annotations
+and class-field documentation. Source code is never imported or rewritten.
+Arx collection requires a future frontend documentation adapter and is
+explicitly rejected today. Inherited members,
+incremental builds, preview serving, and cross-project links are follow-ups.
+
+The generated search data has no bundled interactive search UI yet.
+
+## Development
+
+```console
+poetry run makim all.ci
+poetry check --lock
+```
+
+Infrastructure is adapted from [Douki](https://github.com/arxlang/douki).
+See [contributing](docs/contributing.md) for the pinned source and workflow.
+

doukimd-1.0.0/README.md

@@ -0,0 +1,56 @@
+# DoukiMD
+
+Markdown documentation with first-class
+[Douki](https://github.com/arxlang/douki) API references.
+
+DoukiMD is an opinionated static documentation engine for projects using
+Douki YAML docstrings. This initial version supports Python projects.
+
+## Run from source
+
+```console
+poetry install
+poetry run doukimd build --config examples/basic/doukimd.yaml
+```
+
+Open `examples/basic/build/index.html` to view the generated site.
+Use `doukimd check` to validate without writing files.
+
+## Included
+
+- Markdown pages with validated YAML front matter.
+- Opt-in Jinja in Markdown with project, page, data, and API metadata.
+- Static Python API extraction and validation against Douki's shipped schema.
+- Public re-exports, properties, data declarations, and callable variants.
+- Named API source folders with per-page and per-block selection.
+- Native API blocks, virtual API pages, and forward API references.
+- Ordered navbar menus and product sidebars with source-scoped API trees.
+- Page layouts, trusted HTML opt-in, local branding, and extra stylesheets.
+- Local link and heading validation, assets, code highlighting, and JSON
+  symbol and search inventories.
+- A bundled theme, local Jinja theme overrides, and explicit context plugins.
+- Safe replacement of managed output after successful builds.
+
+See [authoring and configuration](docs/usage.md) and the complete
+[example project](examples/basic).
+
+## Initial scope
+
+Python 3.10–3.14 is supported. Handwritten modules, classes, and callables
+require valid Douki docstrings. Data declarations can use their annotations
+and class-field documentation. Source code is never imported or rewritten.
+Arx collection requires a future frontend documentation adapter and is
+explicitly rejected today. Inherited members,
+incremental builds, preview serving, and cross-project links are follow-ups.
+
+The generated search data has no bundled interactive search UI yet.
+
+## Development
+
+```console
+poetry run makim all.ci
+poetry check --lock
+```
+
+Infrastructure is adapted from [Douki](https://github.com/arxlang/douki).
+See [contributing](docs/contributing.md) for the pinned source and workflow.

doukimd-1.0.0/pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "doukimd"
+version = "1.0.0"  # semantic-release
+description = "Markdown documentation with first-class Douki API references"
+readme = "README.md"
+authors = [{name = "Ivan Ogasawara", email = "ivan.ogasawara@gmail.com"}]
+license = "BSD-3-Clause"
+requires-python = ">=3.10,<4"
+dependencies = [
+  "atpublic>=5,<6",
+  "click>=8.1,<9",
+  "douki>=0.12.1,<0.13",
+  "griffe>=1.15,<2",
+  "Jinja2>=3.1.6,<4",
+  "jsonschema>=4.23,<5",
+  "markdown-it-py>=3,<5",
+  "mdit-py-plugins>=0.4,<0.7",
+  "pluggy>=1.5,<2",
+  "plum-dispatch>=2.5,<3",
+  "pydantic>=2.10,<3",
+  "Pygments>=2.18,<3",
+  "PyYAML>=6,<7",
+  "typeguard>=4.4,<5",
+]
+
+[project.scripts]
+doukimd = "doukimd.cli:main"
+
+[build-system]
+requires = ["poetry-core>=2,<3"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [{include = "doukimd", from = "src"}]
+include = ["src/doukimd/py.typed", "src/doukimd/themes/**/*"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8,<10"
+pytest-cov = ">=5,<8"
+pre-commit = ">=3.8,<5"
+ruff = ">=0.9,<0.18"
+mypy = ">=1.14,<3"
+types-pyyaml = ">=6"
+types-jsonschema = ">=4"
+types-Pygments = ">=2"
+makim = "1.27.0"
+bandit = ">=1.8,<2"
+vulture = ">=2.14,<3"
+mccabe = ">=0.7,<0.8"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_configs = true
+files = ["src/doukimd"]
+
+[[tool.mypy.overrides]]
+module = ["doukimd.api", "doukimd.collection"]
+disable_error_code = ["no-redef"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -p no:xonsh"
+
+[tool.coverage.run]
+source = ["doukimd"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 90
+
+[tool.ruff]
+target-version = "py310"
+line-length = 79
+
+[tool.ruff.lint]
+select = ["E", "F", "YTT", "RUF", "I", "UP006", "UP007"]
+
+[tool.ruff.lint.isort]
+lines-between-types = 1
+
+[tool.ruff.lint.per-file-ignores]
+"src/doukimd/api.py" = ["F811"]
+"src/doukimd/collection.py" = ["F811"]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+
+[tool.vulture]
+paths = ["src/doukimd"]
+min_confidence = 80
+ignore_decorators = ["@hookimpl", "@hookspec"]
+
+[tool.douki]
+exclude = ["tests/fixtures/*"]

doukimd-1.0.0/src/doukimd/__init__.py

@@ -0,0 +1,28 @@
+"""
+title: DoukiMD, Markdown documentation powered by Douki.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from public import public
+
+from doukimd.runtime import typechecked
+
+
+@public
+@typechecked
+def get_version() -> str:
+    """
+    title: Return the installed version or the source-tree fallback.
+    returns:
+      type: str
+    """
+    try:
+        return version('doukimd')
+    except PackageNotFoundError:
+        return '1.0.0'  # semantic-release
+
+
+__version__ = get_version()

doukimd-1.0.0/src/doukimd/__main__.py

@@ -0,0 +1,7 @@
+"""
+title: Invoke the DoukiMD command line interface.
+"""
+
+from doukimd.cli import main
+
+main()

doukimd-1.0.0/src/doukimd/api.py

@@ -0,0 +1,300 @@
+"""
+title: Collect Python declarations without importing project code.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from importlib.resources import files
+from pathlib import Path
+from typing import cast
+
+import griffe
+
+from jsonschema import Draft202012Validator
+from plum import dispatch
+from public import private, public
+
+from doukimd.config import project_path, read_yaml
+from doukimd.errors import BuildError
+from doukimd.models import ApiSymbol, Config
+from doukimd.runtime import typechecked
+
+
+@private
+@typechecked
+def source_path(node: griffe.Object) -> Path:
+    """
+    title: Reject namespace packages without a single source file.
+    parameters:
+      node:
+        type: griffe.Object
+    returns:
+      type: Path
+    """
+    path = node.filepath
+    if not isinstance(path, Path):
+        raise BuildError('api', f'No single source file for {node.path}')
+    return path.resolve()
+
+
+@private
+@typechecked
+def documentation(node: griffe.Object, root: Path) -> dict[str, object]:
+    """
+    title: Validate a source docstring using the installed Douki schema.
+    parameters:
+      node:
+        type: griffe.Object
+      root:
+        type: Path
+    returns:
+      type: dict[str, object]
+    """
+    path = source_path(node)
+    if not path.is_relative_to(root):
+        raise BuildError('api', 'API source escapes the project', path)
+    if node.docstring is None:
+        raise BuildError(
+            'douki', f'Missing Douki docstring: {node.path}', path
+        )
+    data = read_yaml(node.docstring.value, path)
+    schema = json.loads(
+        files('douki').joinpath('schema.json').read_text(encoding='utf-8')
+    )
+    errors = sorted(
+        Draft202012Validator(schema).iter_errors(data),
+        key=lambda error: str(list(error.path)),
+    )
+    if errors:
+        raise BuildError(
+            'douki',
+            f'{node.path}: Douki schema: '
+            + '; '.join(error.message for error in errors),
+            path,
+        )
+    if isinstance(node, griffe.Function) and 'parameters' in data:
+        expected = {
+            parameter.name
+            for parameter in node.parameters
+            if not (
+                isinstance(node.parent, griffe.Class)
+                and 'staticmethod' not in node.labels
+                and parameter.name in {'self', 'cls'}
+            )
+        }
+        parameters = cast(dict[str, object], data['parameters'])
+        if set(parameters) != expected:
+            raise BuildError(
+                'douki',
+                f'{node.path}: documented parameters do not match signature',
+                path,
+            )
+    return data
+
+
+@private
+@dispatch
+@typechecked
+def signature(node: object) -> str:
+    """
+    title: Reject unsupported API declarations.
+    parameters:
+      node:
+        type: object
+    returns:
+      type: str
+    """
+    raise BuildError('api', f'Unsupported declaration: {type(node).__name__}')
+
+
+@dispatch
+@typechecked
+def signature(node: griffe.Module) -> str:
+    """
+    title: Display a module name.
+    parameters:
+      node:
+        type: griffe.Module
+    returns:
+      type: str
+    """
+    return node.path
+
+
+@dispatch
+@typechecked
+def signature(node: griffe.Class | griffe.Function) -> str:
+    """
+    title: Preserve the source signature through Griffe.
+    parameters:
+      node:
+        type: griffe.Class | griffe.Function
+    returns:
+      type: str
+    """
+    return node.signature()
+
+
+@dispatch
+@typechecked
+def signature(node: griffe.Attribute) -> str:
+    """
+    title: Display a data declaration without evaluating its value.
+    parameters:
+      node:
+        type: griffe.Attribute
+    returns:
+      type: str
+    """
+    annotation = f': {node.annotation}' if node.annotation else ''
+    value = f' = {node.value}' if node.value is not None else ''
+    return f'{node.name}{annotation}{value}'
+
+
+@private
+@typechecked
+def hidden(node: griffe.Object) -> bool:
+    """
+    title: Honor explicit visibility rather than underscore naming heuristics.
+    parameters:
+      node:
+        type: griffe.Object
+    returns:
+      type: bool
+    """
+    for decorator in getattr(node, 'decorators', []):
+        name = str(decorator.value).split('(', maxsplit=1)[0]
+        try:
+            resolved = node.resolve(name)
+        except griffe.NameResolutionError:
+            resolved = name
+        if resolved == 'public.private':
+            return True
+    if node.docstring is not None:
+        data = read_yaml(node.docstring.value, source_path(node))
+        return data.get('visibility') in {'private', 'protected', 'internal'}
+    return False
+
+
+@private
+@typechecked
+def visit(node: object, root: Path) -> list[ApiSymbol]:
+    """
+    title: Visit a declaration using the default unscoped collector.
+    parameters:
+      node:
+        type: object
+      root:
+        type: Path
+    returns:
+      type: list[ApiSymbol]
+    """
+    from doukimd.collection import Collector, FunctionCapture
+
+    return cast(
+        list[ApiSymbol],
+        Collector(root, root, None, FunctionCapture()).visit(
+            node, getattr(node, 'path', '')
+        ),
+    )
+
+
+@public
+@typechecked
+def collect_api(root: Path, config: Config) -> dict[str, ApiSymbol]:
+    """
+    title: Collect isolated source folders without importing project code.
+    parameters:
+      root:
+        type: Path
+      config:
+        type: Config
+    returns:
+      type: dict[str, ApiSymbol]
+    """
+    from doukimd.collection import Collector, FunctionCapture
+
+    inventory: dict[str, ApiSymbol] = {}
+    names: set[str] = set()
+    for source in config.api.sources:
+        if source.name is not None:
+            if source.name in names:
+                raise BuildError('api', f'Duplicate API source: {source.name}')
+            names.add(source.name)
+        search = project_path(root, source.root)
+        if not search.is_dir():
+            raise BuildError('api', 'API source folder does not exist', search)
+        for path in search.rglob('*'):
+            if path.is_symlink() and not path.resolve().is_relative_to(search):
+                raise BuildError(
+                    'api', 'API source escapes selected folder', path
+                )
+        capture = FunctionCapture()
+        modules = list(source.modules)
+        loader_search = search
+        if not modules:
+            if (search / '__init__.py').is_file():
+                loader_search = search.parent
+                modules = [search.name]
+            else:
+                for directory in search.iterdir():
+                    if (
+                        directory.is_dir()
+                        and not (directory / '__init__.py').is_file()
+                        and any(directory.rglob('*.py'))
+                    ):
+                        raise BuildError(
+                            'api',
+                            'Namespace packages are unsupported',
+                            directory,
+                        )
+                modules = sorted(
+                    [path.stem for path in search.glob('*.py')]
+                    + [
+                        path.name
+                        for path in search.iterdir()
+                        if path.is_dir() and (path / '__init__.py').is_file()
+                    ]
+                )
+            if not modules:
+                raise BuildError(
+                    'api', 'No Python modules in source folder', search
+                )
+        loader = griffe.GriffeLoader(
+            search_paths=[loader_search],
+            allow_inspection=False,
+            extensions=griffe.load_extensions(capture),
+        )
+        nodes: list[griffe.Object | griffe.Alias] = []
+        try:
+            for module in modules:
+                if (
+                    re.fullmatch(r'[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*', module)
+                    is None
+                ):
+                    raise BuildError('api', f'Invalid module name: {module}')
+                nodes.append(loader.load(module))
+            loader.resolve_aliases(external=False)
+            collector = Collector(root, search, source.name, capture)
+            for node in nodes:
+                for item in collector.visit(node, node.path):
+                    if item.identifier in inventory:
+                        raise BuildError(
+                            'api', f'Duplicate API symbol: {item.identifier}'
+                        )
+                    inventory[item.identifier] = item
+        except (
+            griffe.LoadingError,
+            griffe.NameResolutionError,
+            griffe.AliasResolutionError,
+            griffe.CyclicAliasError,
+            ModuleNotFoundError,
+            KeyError,
+            OSError,
+            SyntaxError,
+        ) as error:
+            raise BuildError('api', str(error), search) from error
+    return inventory

doukimd-1.0.0/src/doukimd/assets.py

@@ -0,0 +1,90 @@
+"""
+title: Copy explicitly selected documentation assets without source escapes.
+"""
+
+from __future__ import annotations
+
+import posixpath
+
+from pathlib import Path
+from urllib.parse import quote
+
+from public import public
+
+from doukimd.config import project_path
+from doukimd.errors import BuildError
+from doukimd.models import Config
+from doukimd.runtime import typechecked
+
+
+@public
+@typechecked
+def copy_assets(root: Path, config: Config) -> dict[str, bytes]:
+    """
+    title: Copy matched docs-relative files and reject unsafe patterns.
+    parameters:
+      root:
+        type: Path
+      config:
+        type: Config
+    returns:
+      type: dict[str, bytes]
+    """
+    docs = project_path(root, config.docs_dir)
+    result: dict[str, bytes] = {}
+    for pattern in config.assets:
+        if (
+            not pattern
+            or Path(pattern).is_absolute()
+            or '..' in Path(pattern).parts
+            or '\\' in pattern
+        ):
+            raise BuildError('assets', f'Invalid asset pattern: {pattern}')
+        # pathlib glob does not recurse through linked directories. Check
+        # their containment too, so an escape is never silently omitted.
+        for path in docs.rglob('*'):
+            if path.is_symlink() and not path.resolve().is_relative_to(docs):
+                raise BuildError(
+                    'assets', 'Asset escapes docs directory', path
+                )
+        matches: list[Path] = []
+        for path in docs.glob(pattern):
+            matches.extend(path.rglob('*') if path.is_dir() else [path])
+        files = [path for path in matches if path.is_file()]
+        if not files and pattern != 'assets/**':
+            raise BuildError('assets', f'No assets match: {pattern}')
+        for path in sorted(files):
+            if not path.resolve().is_relative_to(docs):
+                raise BuildError(
+                    'assets', 'Asset escapes docs directory', path
+                )
+            if path.suffix.lower() in {'.md', '.ipynb'}:
+                raise BuildError(
+                    'assets', 'Asset pattern selects source', path
+                )
+            result[path.relative_to(docs).as_posix()] = path.read_bytes()
+    return result
+
+
+@public
+@typechecked
+def asset_url(
+    value: str | None, route: str, assets: dict[str, bytes]
+) -> str | None:
+    """
+    title: Resolve a configured docs-root asset relative to a planned page.
+    parameters:
+      value:
+        type: str | None
+      route:
+        type: str
+      assets:
+        type: dict[str, bytes]
+    returns:
+      type: str | None
+    """
+    if value is None:
+        return None
+    if value not in assets:
+        raise BuildError('assets', f'Asset is not copied: {value}')
+    return quote(posixpath.relpath(value, posixpath.dirname(route) or '.'))