cpdocs 0.1.0__py3-none-any.whl

cpdocs/cli.py

@@ -0,0 +1,78 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+"""The ``cpdocs`` command."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from . import __version__
+from .build import build_current, build_versions, cmake_module
+from .config import DEFAULT_CONFIG, load_config
+from .python_manifest import write_manifest
+
+
+def _path(value: str) -> Path:
+    return Path(value).expanduser()
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cpdocs", description="Semantic API documentation")
+    parser.add_argument("--version", action="version", version=f"cpdocs {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    def documentation(name: str, help_text: str) -> argparse.ArgumentParser:
+        command = commands.add_parser(name, help=help_text)
+        command.add_argument("--config", type=_path, default=DEFAULT_CONFIG)
+        command.add_argument(
+            "--output",
+            type=_path,
+            default=Path("build"),
+            help="output root; cpdocs writes below <output>/cpdocs (default: build)",
+        )
+        return command
+
+    build = documentation("build", "document the working tree")
+    build.add_argument("--label", default="main", help="version label of the working tree")
+    build.add_argument("--variants", choices=("all", "primary"), default="all")
+
+    versions = documentation("versions", "document the configured branches and tags")
+    versions.add_argument("--tags", help="override versions.tags.select")
+
+    manifest = commands.add_parser("manifest", help="answer a cpdocs request as a build system")
+    kinds = manifest.add_subparsers(dest="kind", required=True)
+    python = kinds.add_parser("python", help="plain pyproject.toml project")
+    python.add_argument("--request", type=_path, required=True)
+    python.add_argument("--package", required=True)
+    python.add_argument("--source", required=True, help="package directory, relative to the root")
+
+    commands.add_parser("cmake-module", help="print the path of the CMake adapter")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    arguments = parser.parse_args(argv)
+    try:
+        if arguments.command == "cmake-module":
+            print(cmake_module())
+        elif arguments.command == "manifest":
+            write_manifest(
+                arguments.request, package=arguments.package, package_source=arguments.source
+            )
+        else:
+            config = load_config(arguments.config)
+            output = arguments.output.resolve()
+            if arguments.command == "build":
+                build_current(
+                    config, output=output, version=arguments.label, variants=arguments.variants
+                )
+            else:
+                build_versions(config, output=output, tags=arguments.tags)
+    except RuntimeError as error:
+        parser.exit(1, f"cpdocs: error: {error}\n")
+    return 0
+
+
+__all__ = ["main"]

cpdocs/config.py

@@ -0,0 +1,160 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+"""Loading ``cpdocs.yml``.
+
+The configuration holds documentation and publishing policy only. Everything about the project
+itself -- its name, features, variants, units and API files -- comes from the build system through
+the manifests described in :mod:`cpdocs.contract`. ``cpdocs.yml`` therefore never names a feature or
+a variant.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+CONTRACT_VERSION = 1
+DEFAULT_CONFIG = Path("docs/cpdocs.yml")
+_CHECK_LEVELS = {"ignore", "warn", "fail"}
+_VARIANT_POLICIES = {"all", "primary"}
+
+
+@dataclass(frozen=True)
+class CpdocsConfig:
+    config_file: Path
+    project_root: Path
+    describe: tuple[tuple[str, ...], ...]
+    branches: tuple[str, ...]
+    branch_variants: str
+    tags: str
+    tag_variants: str
+    default_version: str
+    aliases: dict[str, str]
+    failure: str
+    legacy: str
+    index: Path | None
+    copyright: str | None
+    project_docs: str
+    hide_cpp_namespaces: tuple[str, ...]
+    hide_private_python: bool
+    check_undocumented: str
+    check_broken_references: str
+
+
+def project_root_for(config_file: Path) -> Path:
+    """Return the repository root for a configuration file.
+
+    ``<root>/docs/cpdocs.yml`` belongs to ``<root>``; any other location belongs to the directory
+    that contains the file. All paths in the configuration are relative to this root.
+    """
+
+    parent = config_file.resolve().parent
+    return parent.parent if parent.name == "docs" else parent
+
+
+def _mapping(value: object, name: str) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise RuntimeError(f"cpdocs.yml: {name} must be a mapping")
+    return {str(key): item for key, item in value.items()}
+
+
+def _strings(value: object, name: str) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        return (value,)
+    if not isinstance(value, list):
+        raise RuntimeError(f"cpdocs.yml: {name} must be a list")
+    return tuple(str(item) for item in value)
+
+
+def _choice(value: object, name: str, allowed: set[str], default: str) -> str:
+    result = str(value if value is not None else default)
+    if result not in allowed:
+        raise RuntimeError(f"cpdocs.yml: {name} must be one of {', '.join(sorted(allowed))}")
+    return result
+
+
+def _commands(value: object) -> tuple[tuple[str, ...], ...]:
+    if not isinstance(value, list) or not value:
+        raise RuntimeError("cpdocs.yml: build.describe must be a non-empty list of commands")
+    commands: list[tuple[str, ...]] = []
+    for index, command in enumerate(value):
+        if not isinstance(command, list) or not command:
+            raise RuntimeError(f"cpdocs.yml: build.describe[{index}] must be a non-empty argv list")
+        commands.append(tuple(str(item) for item in command))
+    return tuple(commands)
+
+
+def load_config(path: Path | str = DEFAULT_CONFIG) -> CpdocsConfig:
+    config_file = Path(path).expanduser().resolve()
+    if not config_file.is_file():
+        raise RuntimeError(f"cpdocs configuration does not exist: {config_file}")
+    raw = yaml.safe_load(config_file.read_text(encoding="utf-8")) or {}
+    if not isinstance(raw, dict):
+        raise RuntimeError("cpdocs.yml: top level must be a mapping")
+    if raw.get("contract") != CONTRACT_VERSION:
+        raise RuntimeError(
+            f"cpdocs.yml: contract must be {CONTRACT_VERSION}, found {raw.get('contract')!r}"
+        )
+    known = {"contract", "build", "versions", "site", "api", "checks"}
+    unknown = sorted(set(raw) - known)
+    if unknown:
+        raise RuntimeError(f"cpdocs.yml: unknown top-level keys: {', '.join(unknown)}")
+
+    root = project_root_for(config_file)
+    build = _mapping(raw.get("build"), "build")
+    versions = _mapping(raw.get("versions"), "versions")
+    branches = _mapping(versions.get("branches"), "versions.branches")
+    tags = _mapping(versions.get("tags"), "versions.tags")
+    site = _mapping(raw.get("site"), "site")
+    api = _mapping(raw.get("api"), "api")
+    hide = _mapping(api.get("hide"), "api.hide")
+    checks = _mapping(raw.get("checks"), "checks")
+
+    index_value = site.get("index")
+    index = (
+        (root / str(index_value)).resolve() if index_value else root / "docs" / "api" / "index.md"
+    )
+    aliases = {
+        str(key): str(value)
+        for key, value in _mapping(versions.get("aliases"), "versions.aliases").items()
+    }
+    copyright_value = site.get("copyright")
+
+    return CpdocsConfig(
+        config_file=config_file,
+        project_root=root,
+        describe=_commands(build.get("describe")),
+        branches=_strings(branches.get("include", ["main"]), "versions.branches.include"),
+        branch_variants=_choice(
+            branches.get("variants"), "versions.branches.variants", _VARIANT_POLICIES, "all"
+        ),
+        tags=str(tags.get("select", "all")).strip(),
+        tag_variants=_choice(
+            tags.get("variants"), "versions.tags.variants", _VARIANT_POLICIES, "all"
+        ),
+        default_version=str(versions.get("default") or "latest-tag"),
+        aliases=aliases,
+        failure=_choice(versions.get("failure"), "versions.failure", {"skip", "fail"}, "fail"),
+        legacy=_choice(versions.get("legacy"), "versions.legacy", {"current", "skip"}, "current"),
+        index=index if index.is_file() else None,
+        copyright=str(copyright_value) if copyright_value is not None else None,
+        project_docs=str(site.get("project-docs") or "auto"),
+        hide_cpp_namespaces=_strings(hide.get("cpp-namespaces"), "api.hide.cpp-namespaces"),
+        hide_private_python=_choice(
+            hide.get("python-modules"), "api.hide.python-modules", {"private", "none"}, "private"
+        )
+        == "private",
+        check_undocumented=_choice(
+            checks.get("undocumented"), "checks.undocumented", _CHECK_LEVELS, "ignore"
+        ),
+        check_broken_references=_choice(
+            checks.get("broken-references"), "checks.broken-references", _CHECK_LEVELS, "warn"
+        ),
+    )

cpdocs/contract.py

@@ -0,0 +1,407 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+"""The contract between cpdocs and a project's build system.
+
+cpdocs never knows how a project is built. It hands the build system a *request* and reads back a
+*manifest*. There are two phases:
+
+``describe``
+    The build system reports the project identity, its feature axes, the documentation units and
+    the variants worth documenting. Every variant carries the commands that make it concrete.
+
+``variant``
+    The build system has been configured for exactly one variant and reports, per unit, which files
+    form the public API and how they must be parsed.
+
+The normative description lives in ``docs/web/reference/contract.md``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+CONTRACT_VERSION = 1
+LANGUAGES = ("c", "cpp", "python", "rust")
+
+
+class ContractError(RuntimeError):
+    """A request or manifest does not satisfy the cpdocs build-system contract."""
+
+
+# --------------------------------------------------------------------------------------------------
+# Request
+# --------------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Request:
+    phase: str
+    ref: str
+    ref_kind: str
+    source: Path
+    build: Path
+    manifest: Path
+    variant: str | None
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "cpdocs-request": CONTRACT_VERSION,
+            "phase": self.phase,
+            "ref": self.ref,
+            "ref-kind": self.ref_kind,
+            "variant": self.variant,
+            "source": str(self.source),
+            "build": str(self.build),
+            "manifest": str(self.manifest),
+        }
+
+    def write(self, path: Path) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(self.to_json(), indent=2) + "\n", encoding="utf-8")
+
+
+def read_request(path: Path) -> Request:
+    raw = _load_json(path, "request")
+    if raw.get("cpdocs-request") != CONTRACT_VERSION:
+        raise ContractError(f"{path}: unsupported cpdocs-request {raw.get('cpdocs-request')!r}")
+    phase = _string(raw, "phase", path)
+    if phase not in {"describe", "variant"}:
+        raise ContractError(f"{path}: phase must be 'describe' or 'variant'")
+    variant = raw.get("variant")
+    if phase == "variant" and not isinstance(variant, str):
+        raise ContractError(f"{path}: a variant request must name its variant")
+    return Request(
+        phase=phase,
+        ref=_string(raw, "ref", path),
+        ref_kind=_string(raw, "ref-kind", path),
+        source=Path(_string(raw, "source", path)),
+        build=Path(_string(raw, "build", path)),
+        manifest=Path(_string(raw, "manifest", path)),
+        variant=variant if isinstance(variant, str) else None,
+    )
+
+
+# --------------------------------------------------------------------------------------------------
+# Describe manifest
+# --------------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class FeatureAxis:
+    name: str
+    values: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class UnitDeclaration:
+    id: str
+    language: str
+
+
+@dataclass(frozen=True)
+class VariantDeclaration:
+    name: str
+    primary: bool
+    features: dict[str, tuple[str, ...]]
+    commands: tuple[tuple[str, ...], ...]
+
+
+@dataclass(frozen=True)
+class Description:
+    project: str
+    version: str
+    features: tuple[FeatureAxis, ...]
+    units: tuple[UnitDeclaration, ...]
+    variants: tuple[VariantDeclaration, ...]
+    generator: str
+
+    @property
+    def primary(self) -> VariantDeclaration:
+        return next(variant for variant in self.variants if variant.primary)
+
+    def variant(self, name: str) -> VariantDeclaration:
+        for variant in self.variants:
+            if variant.name == name:
+                return variant
+        raise ContractError(f"describe manifest has no variant {name!r}")
+
+
+def read_description(path: Path) -> Description:
+    raw = _load_json(path, "describe manifest")
+    _check_header(raw, path, "describe")
+    project = _mapping(raw.get("project"), "project", path)
+
+    axes: list[FeatureAxis] = []
+    for name, value in _mapping(raw.get("features", {}), "features", path).items():
+        data = _mapping(value, f"features.{name}", path)
+        values = _string_tuple(data.get("values"), f"features.{name}.values", path)
+        if len(set(values)) != len(values):
+            raise ContractError(f"{path}: features.{name}.values contains duplicates")
+        axes.append(FeatureAxis(name=name, values=values))
+    axis_values = {axis.name: set(axis.values) for axis in axes}
+
+    units = _units(raw.get("units"), path)
+
+    variants: list[VariantDeclaration] = []
+    raw_variants = raw.get("variants")
+    if not isinstance(raw_variants, list) or not raw_variants:
+        raise ContractError(f"{path}: variants must be a non-empty list")
+    for index, value in enumerate(raw_variants):
+        where = f"variants[{index}]"
+        data = _mapping(value, where, path)
+        name = _string(data, "name", path, where)
+        features = _features(data.get("features", {}), f"{where}.features", path)
+        for axis, selected in features.items():
+            if axis not in axis_values:
+                raise ContractError(f"{path}: {where} uses undeclared feature axis {axis!r}")
+            unknown = sorted(set(selected) - axis_values[axis])
+            if unknown:
+                raise ContractError(
+                    f"{path}: {where} selects unknown {axis} values: {', '.join(unknown)}"
+                )
+        commands = data.get("commands")
+        if not isinstance(commands, list):
+            raise ContractError(f"{path}: {where}.commands must be a list of argv lists")
+        variants.append(
+            VariantDeclaration(
+                name=name,
+                primary=bool(data.get("primary", False)),
+                features=features,
+                commands=tuple(
+                    _string_tuple(command, f"{where}.commands[{number}]", path)
+                    for number, command in enumerate(commands)
+                ),
+            )
+        )
+
+    names = [variant.name for variant in variants]
+    if len(set(names)) != len(names):
+        raise ContractError(f"{path}: variant names must be unique")
+    primaries = [variant.name for variant in variants if variant.primary]
+    if len(primaries) != 1:
+        raise ContractError(f"{path}: exactly one variant must be primary, found {len(primaries)}")
+
+    return Description(
+        project=_string(project, "name", path, "project"),
+        version=str(project.get("version") or ""),
+        features=tuple(axes),
+        units=units,
+        variants=tuple(variants),
+        generator=str(raw.get("generator") or ""),
+    )
+
+
+# --------------------------------------------------------------------------------------------------
+# Variant manifest
+# --------------------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ApiRoot:
+    path: Path
+    generated: bool
+
+
+@dataclass(frozen=True)
+class ParseOptions:
+    standard: str
+    include: tuple[Path, ...]
+    system_include: tuple[Path, ...]
+    define: tuple[str, ...]
+    flags: tuple[str, ...]
+    compile_database: Path | None
+
+
+@dataclass(frozen=True)
+class UnitManifest:
+    id: str
+    language: str
+    api: tuple[ApiRoot, ...]
+    parse: ParseOptions | None
+    package: str | None
+    rustdoc_json: Path | None
+
+
+@dataclass(frozen=True)
+class VariantManifest:
+    variant: str
+    features: dict[str, tuple[str, ...]]
+    units: tuple[UnitManifest, ...]
+
+
+def read_variant_manifest(path: Path, *, source: Path) -> VariantManifest:
+    """Read one variant manifest; relative paths are resolved against ``source``."""
+
+    raw = _load_json(path, "variant manifest")
+    _check_header(raw, path, "variant")
+    units: list[UnitManifest] = []
+    for declaration, value in zip(_units(raw.get("units"), path), raw["units"], strict=True):
+        where = f"unit {declaration.id!r}"
+        data = _mapping(value, where, path)
+        roots = data.get("api", [])
+        if not isinstance(roots, list):
+            raise ContractError(f"{path}: {where}: api must be a list")
+        api: list[ApiRoot] = []
+        for index, root in enumerate(roots):
+            root_data = _mapping(root, f"{where}.api[{index}]", path)
+            api.append(
+                ApiRoot(
+                    path=_path(_string(root_data, "path", path, where), source),
+                    generated=bool(root_data.get("generated", False)),
+                )
+            )
+
+        parse: ParseOptions | None = None
+        package: str | None = None
+        rustdoc_json: Path | None = None
+        if declaration.language in {"c", "cpp"}:
+            if not api:
+                raise ContractError(f"{path}: {where}: a C/C++ unit needs at least one API root")
+            options = _mapping(data.get("parse", {}), f"{where}.parse", path)
+            database = options.get("compile-database")
+            parse = ParseOptions(
+                standard=str(options.get("standard") or ""),
+                include=tuple(
+                    _path(item, source)
+                    for item in _string_tuple(options.get("include", []), "include", path)
+                ),
+                system_include=tuple(
+                    _path(item, source)
+                    for item in _string_tuple(
+                        options.get("system-include", []), "system-include", path
+                    )
+                ),
+                define=_string_tuple(options.get("define", []), "define", path),
+                flags=_string_tuple(options.get("flags", []), "flags", path),
+                compile_database=_path(str(database), source) if database else None,
+            )
+        elif declaration.language == "python":
+            if len(api) != 1:
+                raise ContractError(f"{path}: {where}: a Python unit needs exactly one API root")
+            package = _string(data, "package", path, where)
+        elif declaration.language == "rust":
+            rustdoc_json = _path(_string(data, "rustdoc-json", path, where), source)
+
+        units.append(
+            UnitManifest(
+                id=declaration.id,
+                language=declaration.language,
+                api=tuple(api),
+                parse=parse,
+                package=package,
+                rustdoc_json=rustdoc_json,
+            )
+        )
+
+    return VariantManifest(
+        variant=_string(raw, "variant", path),
+        features=_features(raw.get("features", {}), "features", path),
+        units=tuple(units),
+    )
+
+
+def check_variant(
+    manifest: VariantManifest, *, description: Description, requested: str, path: Path
+) -> None:
+    """Reject a variant manifest that disagrees with what was requested and described."""
+
+    if manifest.variant != requested:
+        raise ContractError(
+            f"{path}: build system answered for variant {manifest.variant!r}, "
+            f"cpdocs requested {requested!r}"
+        )
+    declared = description.variant(requested)
+    expected = {axis: tuple(sorted(values)) for axis, values in declared.features.items()}
+    actual = {axis: tuple(sorted(values)) for axis, values in manifest.features.items()}
+    for axis in {axis.name for axis in description.features}:
+        expected.setdefault(axis, ())
+        actual.setdefault(axis, ())
+    if expected != actual:
+        raise ContractError(
+            f"{path}: variant {requested!r} was configured with features {actual}, "
+            f"but the describe manifest declares {expected}"
+        )
+    described = [(unit.id, unit.language) for unit in description.units]
+    reported = [(unit.id, unit.language) for unit in manifest.units]
+    if sorted(described) != sorted(reported):
+        raise ContractError(
+            f"{path}: variant {requested!r} reports units {reported}, described units are "
+            f"{described}"
+        )
+
+
+# --------------------------------------------------------------------------------------------------
+# Helpers
+# --------------------------------------------------------------------------------------------------
+
+
+def _load_json(path: Path, what: str) -> dict[str, Any]:
+    if not path.is_file():
+        raise ContractError(f"the build system did not write the {what} {path}")
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ContractError(f"cannot read {what} {path}: {error}") from error
+    if not isinstance(raw, dict):
+        raise ContractError(f"{path}: {what} must be a JSON object")
+    return raw
+
+
+def _check_header(raw: dict[str, Any], path: Path, kind: str) -> None:
+    if raw.get("cpdocs-manifest") != CONTRACT_VERSION:
+        raise ContractError(f"{path}: unsupported cpdocs-manifest {raw.get('cpdocs-manifest')!r}")
+    if raw.get("kind") != kind:
+        raise ContractError(f"{path}: expected a {kind!r} manifest, found {raw.get('kind')!r}")
+
+
+def _mapping(value: object, name: str, path: Path) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ContractError(f"{path}: {name} must be an object")
+    return {str(key): item for key, item in value.items()}
+
+
+def _string(data: dict[str, Any], key: str, path: Path, where: str = "") -> str:
+    value = data.get(key)
+    if not isinstance(value, str) or not value:
+        prefix = f"{where}." if where else ""
+        raise ContractError(f"{path}: {prefix}{key} must be a non-empty string")
+    return value
+
+
+def _string_tuple(value: object, name: str, path: Path) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise ContractError(f"{path}: {name} must be a list of strings")
+    return tuple(value)
+
+
+def _features(value: object, name: str, path: Path) -> dict[str, tuple[str, ...]]:
+    data = _mapping(value, name, path)
+    return {axis: _string_tuple(item, f"{name}.{axis}", path) for axis, item in data.items()}
+
+
+def _units(value: object, path: Path) -> tuple[UnitDeclaration, ...]:
+    if not isinstance(value, list) or not value:
+        raise ContractError(f"{path}: units must be a non-empty list")
+    units: list[UnitDeclaration] = []
+    for index, item in enumerate(value):
+        data = _mapping(item, f"units[{index}]", path)
+        language = _string(data, "language", path, f"units[{index}]")
+        if language not in LANGUAGES:
+            raise ContractError(
+                f"{path}: units[{index}].language must be one of {', '.join(LANGUAGES)}"
+            )
+        units.append(
+            UnitDeclaration(id=_string(data, "id", path, f"units[{index}]"), language=language)
+        )
+    ids = [unit.id for unit in units]
+    if len(set(ids)) != len(ids):
+        raise ContractError(f"{path}: unit ids must be unique")
+    return tuple(units)
+
+
+def _path(value: str, source: Path) -> Path:
+    path = Path(value).expanduser()
+    return (path if path.is_absolute() else source / path).resolve()