cpdocs 0.1.0__py3-none-any.whl

cpdocs/model.py

@@ -0,0 +1,228 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+"""Language-neutral API graph used by cpdocs' reference renderer."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class SourceLocation:
+    path: str
+    line: int | None = None
+    column: int | None = None
+
+
+@dataclass(frozen=True)
+class ApiParameter:
+    name: str
+    type: str = ""
+    default: str | None = None
+    kind: str = ""
+
+
+@dataclass(frozen=True)
+class ApiSignature:
+    parameters: tuple[ApiParameter, ...] = ()
+    returns: str = ""
+    qualifiers: tuple[str, ...] = ()
+    spelling: str = ""
+    template: str = ""
+    # Documentation and location of this overload; not part of its identity.
+    documentation: str = field(default="", compare=False)
+    source: SourceLocation | None = field(default=None, compare=False)
+
+    @property
+    def compact(self) -> str:
+        values = [parameter.type or parameter.name or "?" for parameter in self.parameters]
+        return f"({', '.join(values)})"
+
+
+@dataclass
+class ApiEntity:
+    id: str
+    language: str
+    kind: str
+    name: str
+    qualified_name: str
+    parent: str | None = None
+    signatures: list[ApiSignature] = field(default_factory=list)
+    documentation: str = ""
+    source: SourceLocation | None = None
+    properties: list[str] = field(default_factory=list)
+    variants: list[str] = field(default_factory=list)
+    children: list[str] = field(default_factory=list)
+    bases: list[str] = field(default_factory=list)
+    aliases: list[str] = field(default_factory=list)
+    related: list[str] = field(default_factory=list)
+    template: str = ""
+    declaration: str = ""
+    # Variants of each signature, parallel to ``signatures``; empty when unknown.
+    signature_variants: list[list[str]] = field(default_factory=list)
+
+    @property
+    def navigation_label(self) -> str:
+        # The outline is deliberately name-only.  Detailed/overload signatures belong to the
+        # entity page and its local "On this page" navigation, not to the global API tree.
+        return self.name
+
+    @property
+    def member_label(self) -> str:
+        if self.kind in {"function", "method", "constructor"}:
+            return f"{self.name}()"
+        return self.name
+
+
+@dataclass
+class ApiGraph:
+    project: str
+    version: str
+    language: str
+    entities: dict[str, ApiEntity] = field(default_factory=dict)
+    variants: dict[str, dict[str, object]] = field(default_factory=dict)
+    sources: dict[str, str] = field(default_factory=dict)
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    def add(self, entity: ApiEntity) -> None:
+        existing = self.entities.get(entity.id)
+        if existing is None:
+            self.entities[entity.id] = entity
+            return
+
+        while len(existing.signature_variants) < len(existing.signatures):
+            existing.signature_variants.append([])
+        for index, signature in enumerate(entity.signatures):
+            incoming = (
+                entity.signature_variants[index] if index < len(entity.signature_variants) else []
+            )
+            if signature not in existing.signatures:
+                existing.signatures.append(signature)
+                existing.signature_variants.append(list(incoming))
+                continue
+            known = existing.signature_variants[existing.signatures.index(signature)]
+            known.extend(value for value in incoming if value not in known)
+        for value in entity.properties:
+            if value not in existing.properties:
+                existing.properties.append(value)
+        for value in entity.variants:
+            if value not in existing.variants:
+                existing.variants.append(value)
+        for value in entity.children:
+            if value not in existing.children:
+                existing.children.append(value)
+        for value in entity.bases:
+            if value not in existing.bases:
+                existing.bases.append(value)
+        for value in entity.aliases:
+            if value not in existing.aliases:
+                existing.aliases.append(value)
+        for value in entity.related:
+            if value not in existing.related:
+                existing.related.append(value)
+        if not existing.documentation and entity.documentation:
+            existing.documentation = entity.documentation
+        if existing.source is None and entity.source is not None:
+            existing.source = entity.source
+        if not existing.template and entity.template:
+            existing.template = entity.template
+        if not existing.declaration and entity.declaration:
+            existing.declaration = entity.declaration
+
+    def rebuild_children(self) -> None:
+        for entity in self.entities.values():
+            entity.children = []
+        for entity in self.entities.values():
+            if entity.parent and entity.parent in self.entities:
+                parent = self.entities[entity.parent]
+                if entity.id not in parent.children:
+                    parent.children.append(entity.id)
+        for entity in self.entities.values():
+            entity.children.sort(key=lambda key: entity_sort_key(self.entities[key]))
+
+    def roots(self) -> list[ApiEntity]:
+        values = [
+            entity
+            for entity in self.entities.values()
+            if not entity.parent or entity.parent not in self.entities
+        ]
+        return sorted(values, key=entity_sort_key)
+
+
+def entity_sort_key(entity: ApiEntity) -> tuple[int, str, str]:
+    order = {
+        "package": 0,
+        "module": 1,
+        "namespace": 1,
+        "class": 2,
+        "struct": 2,
+        "union": 2,
+        "trait": 2,
+        "protocol": 2,
+        "enum": 3,
+        "type_alias": 4,
+        "constructor": 5,
+        "method": 6,
+        "function": 6,
+        "property": 7,
+        "attribute": 8,
+        "variable": 8,
+        "constant": 8,
+        "macro": 9,
+        "concept": 4,
+        "deduction_guide": 5,
+    }
+    return (order.get(entity.kind, 50), entity.name.casefold(), entity.qualified_name)
+
+
+def stable_entity_id(language: str, kind: str, qualified_name: str, signature_key: str = "") -> str:
+    suffix = f"::{signature_key}" if signature_key else ""
+    return f"{language}:{kind}:{qualified_name}{suffix}"
+
+
+def relative_source_path(path: str | Path, project_root: Path) -> str:
+    source = Path(path)
+    try:
+        return source.resolve().relative_to(project_root.resolve()).as_posix()
+    except (OSError, ValueError):
+        return source.as_posix()
+
+
+def merge_graphs(
+    graphs: Iterable[tuple[str, ApiGraph]], *, project: str, version: str, language: str
+) -> ApiGraph:
+    merged = ApiGraph(project=project, version=version, language=language)
+    for variant_name, graph in graphs:
+        for key, value in graph.metadata.items():
+            merged.metadata.setdefault(key, value)
+        merged.variants[variant_name] = graph.variants.get(variant_name, {})
+        for source_path, content in graph.sources.items():
+            merged.sources.setdefault(source_path, content)
+        for entity in graph.entities.values():
+            entity_copy = ApiEntity(
+                id=entity.id,
+                language=entity.language,
+                kind=entity.kind,
+                name=entity.name,
+                qualified_name=entity.qualified_name,
+                parent=entity.parent,
+                signatures=list(entity.signatures),
+                documentation=entity.documentation,
+                source=entity.source,
+                properties=list(entity.properties),
+                variants=list(entity.variants),
+                children=list(entity.children),
+                bases=list(entity.bases),
+                aliases=list(entity.aliases),
+                related=list(entity.related),
+                template=entity.template,
+                declaration=entity.declaration,
+                signature_variants=[[variant_name] for _signature in entity.signatures],
+            )
+            if variant_name not in entity_copy.variants:
+                entity_copy.variants.append(variant_name)
+            merged.add(entity_copy)
+    merged.rebuild_children()
+    return merged

cpdocs/properdocs_core.py

@@ -0,0 +1,158 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+"""Framework-independent helpers used by the ProperDocs cpdocs plugin."""
+
+from __future__ import annotations
+
+import posixpath
+import re
+import shutil
+from collections.abc import Callable
+from pathlib import Path, PurePosixPath
+from urllib.parse import quote
+
+_APIDOCS_REFERENCE = re.compile(
+    r"@apidocs(?:\[(?P<version>[^\]]+)\])?::"
+    r"(?P<symbol>[A-Za-z_](?:[A-Za-z0-9_:.]*[A-Za-z0-9_])?)"
+)
+
+
+def repository_provider(repo_url: str, extra: dict[str, object]) -> str:
+    explicit = str(extra.get("cpdocs_repo_provider") or "").strip().lower()
+    if explicit:
+        return explicit
+    host = repo_url.lower()
+    if "github" in host:
+        return "github"
+    if "bitbucket" in host:
+        return "bitbucket"
+    return "gitlab"
+
+
+def _repository_base(repo_url: str) -> str:
+    value = repo_url.rstrip("/")
+    return value[:-4] if value.endswith(".git") else value
+
+
+def source_url(repo_url: str, provider: str, ref: str, source_path: str) -> str:
+    base = _repository_base(repo_url)
+    ref_part = quote(ref, safe="/")
+    path_part = quote(source_path, safe="/")
+    if provider == "github":
+        return f"{base}/blob/{ref_part}/{path_part}"
+    if provider == "bitbucket":
+        return f"{base}/src/{ref_part}/{path_part}"
+    return f"{base}/-/blob/{ref_part}/{path_part}"
+
+
+def edit_url(repo_url: str, provider: str, ref: str, source_path: str) -> str:
+    base = _repository_base(repo_url)
+    ref_part = quote(ref, safe="/")
+    path_part = quote(source_path, safe="/")
+    if provider == "github":
+        return f"{base}/edit/{ref_part}/{path_part}"
+    if provider == "bitbucket":
+        return f"{base}/src/{ref_part}/{path_part}?mode=edit"
+    return f"{base}/-/edit/{ref_part}/{path_part}"
+
+
+def default_issue_url(repo_url: str, provider: str) -> str:
+    base = _repository_base(repo_url)
+    return f"{base}/-/issues/new" if provider == "gitlab" else f"{base}/issues/new"
+
+
+# Fenced code blocks and inline code spans show ``@apidocs`` literally; they are never rewritten.
+_CODE = re.compile(
+    r"^(?P<fence>`{3,}|~{3,}).*?^(?P=fence)[ \t]*$|`[^`\n]+`", re.MULTILINE | re.DOTALL
+)
+
+
+def api_symbol_public_path(symbol: str, version: str, mount: str) -> PurePosixPath:
+    return PurePosixPath(mount) / version / "_symbols" / PurePosixPath(*re.split(r"::|\.", symbol))
+
+
+def resolve_api_references(
+    markdown: str,
+    *,
+    page_dest_uri: str,
+    mount: str,
+    default_version: str,
+    locate: Callable[[str, str], str | None] | None = None,
+    missing: list[tuple[str, str]] | None = None,
+) -> str:
+    """Resolve ``@apidocs`` names to links into the versioned API.
+
+    ``locate(version, symbol)`` returns the entity's page below the version directory, such as
+    ``api/demo/struct-settings/``; the link then points straight at it. Without ``locate``, or for
+    symbols it does not know, the link points at the stable ``_symbols`` alias, and unknown symbols
+    are appended to ``missing`` as ``(version, symbol)``.
+    """
+
+    page_directory = PurePosixPath(page_dest_uri).parent
+
+    def href_to(target: PurePosixPath, anchor: str = "") -> str:
+        relative = posixpath.relpath(target.as_posix(), page_directory.as_posix())
+        return relative + "/" + (f"#{anchor}" if anchor else "")
+
+    def replace(match: re.Match[str]) -> str:
+        symbol = match.group("symbol")
+        version = match.group("version") or default_version
+        found = locate(version, symbol) if locate is not None else None
+        if found:
+            path, _, anchor = found.partition("#")
+            return f"[`{symbol}`]({href_to(PurePosixPath(mount) / version / path, anchor)})"
+        if locate is not None and missing is not None:
+            missing.append((version, symbol))
+        return f"[`{symbol}`]({href_to(api_symbol_public_path(symbol, version, mount))})"
+
+    parts: list[str] = []
+    position = 0
+    for code in _CODE.finditer(markdown):
+        parts.append(_APIDOCS_REFERENCE.sub(replace, markdown[position : code.start()]))
+        parts.append(code.group(0))
+        position = code.end()
+    parts.append(_APIDOCS_REFERENCE.sub(replace, markdown[position:]))
+    return "".join(parts)
+
+
+_VERSIONS_DIRECTIVE = re.compile(r"^@apidocs-versions[ \t]*$", re.MULTILINE)
+
+
+def expand_versions_directive(
+    markdown: str, *, page_dest_uri: str, mount: str, metadata: dict[str, object]
+) -> str:
+    """Replace a line ``@apidocs-versions`` with a list of every published API version."""
+
+    if not _VERSIONS_DIRECTIVE.search(markdown):
+        return markdown
+    page_directory = PurePosixPath(page_dest_uri).parent
+    default = metadata.get("default")
+    aliases = metadata.get("aliases", {})
+    aliases = aliases if isinstance(aliases, dict) else {}
+    lines: list[str] = []
+    versions = metadata.get("versions", [])
+    for entry in versions if isinstance(versions, list) else []:
+        if not isinstance(entry, dict):
+            continue
+        name = str(entry.get("name"))
+        target = PurePosixPath(mount) / name
+        href = posixpath.relpath(target.as_posix(), page_directory.as_posix()) + "/"
+        notes = [str(entry.get("kind", ""))]
+        if name == default:
+            notes.append("default")
+        notes.extend(f"`{alias}`" for alias, value in sorted(aliases.items()) if value == name)
+        lines.append(f"- [{name}]({href}) — " + ", ".join(note for note in notes if note))
+    listing = "\n".join(lines) if lines else "No API version has been published."
+    return _VERSIONS_DIRECTIVE.sub(lambda _match: listing, markdown)
+
+
+def publish_api(source: Path, site_directory: Path, mount: str) -> Path:
+    """Replace the mounted API subtree with cpdocs's complete versioned output."""
+
+    destination = site_directory / Path(*PurePosixPath(mount).parts)
+    if destination.exists():
+        shutil.rmtree(destination)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(source, destination)
+    (site_directory / ".nojekyll").touch()
+    return destination

cpdocs/properdocs_plugin.py

@@ -0,0 +1,236 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+"""ProperDocs plugin which builds the versioned cpdocs API site and mounts it."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import subprocess
+from pathlib import Path, PurePosixPath
+
+from properdocs.config import config_options as c
+from properdocs.exceptions import PluginError
+from properdocs.plugins import BasePlugin
+
+from cpdocs.build import Layout, build_versions, recorded_default_version
+from cpdocs.config import DEFAULT_CONFIG, CpdocsConfig, load_config
+
+from .properdocs_core import (
+    default_issue_url,
+    edit_url,
+    expand_versions_directive,
+    publish_api,
+    repository_provider,
+    resolve_api_references,
+    source_url,
+)
+
+_LOG = logging.getLogger("properdocs.plugins.cpdocs")
+
+
+def _symbol_key(symbol: str) -> tuple[str, ...]:
+    return tuple(part for part in re.split(r"::|\.", symbol) if part)
+
+
+class CpdocsPlugin(BasePlugin):
+    """Build cpdocs before ProperDocs and mount it into the final static site."""
+
+    config_scheme = (
+        ("config", c.Type(str, default=str(DEFAULT_CONFIG))),
+        ("output", c.Type(str, default="build")),
+        ("mount", c.Type(str, default="reference/api")),
+    )
+
+    def __init__(self) -> None:
+        self._project_root: Path | None = None
+        self._cpdocs: CpdocsConfig | None = None
+        self._last_fingerprint: tuple[tuple[str, int, int], ...] | None = None
+        self._serve_active = False
+        self._symbols: dict[str, dict[tuple[str, ...], str]] = {}
+
+    @property
+    def mount(self) -> str:
+        value = str(self.config.get("mount", "reference/api")).strip("/")
+        if not value:
+            raise PluginError("cpdocs: mount must not be the site root")
+        return value
+
+    @property
+    def output(self) -> Path:
+        assert self._project_root is not None
+        path = Path(str(self.config.get("output", "build")))
+        return path if path.is_absolute() else self._project_root / path
+
+    def on_startup(self, *, command: str, dirty: bool = False) -> None:
+        del dirty
+        self._serve_active = command == "serve"
+
+    def _config_file(self, config) -> Path:
+        value = getattr(config, "config_file_path", None)
+        if value:
+            return Path(value).resolve()
+        return (Path.cwd() / "properdocs.yml").resolve()
+
+    def on_config(self, config):
+        self._project_root = self._config_file(config).parent
+        cpdocs_file = Path(str(self.config.get("config", DEFAULT_CONFIG)))
+        if not cpdocs_file.is_absolute():
+            cpdocs_file = self._project_root / cpdocs_file
+        try:
+            self._cpdocs = load_config(cpdocs_file)
+        except RuntimeError as error:
+            raise PluginError(f"cpdocs: {error}") from error
+
+        extra = dict(config.get("extra", {}) or {})
+        repo_url = str(config.get("repo_url") or "").strip()
+        if repo_url:
+            provider = repository_provider(repo_url, extra)
+            extra["cpdocs_repo_provider"] = provider
+            extra["cpdocs_source_ref"] = os.environ.get("CPDOCS_SOURCE_REF") or self._source_ref()
+            if not extra.get("cpdocs_issue_url"):
+                extra["cpdocs_issue_url"] = default_issue_url(repo_url, provider)
+        config["extra"] = extra
+        return config
+
+    def _git(self, *arguments: str) -> subprocess.CompletedProcess[str]:
+        assert self._project_root is not None
+        return subprocess.run(
+            ["git", *arguments],
+            cwd=self._project_root,
+            check=False,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+        )
+
+    def _source_ref(self) -> str:
+        result = self._git("symbolic-ref", "--quiet", "--short", "HEAD")
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip()
+        result = self._git("describe", "--tags", "--exact-match")
+        return result.stdout.strip() if result.returncode == 0 else "main"
+
+    def _watched_files(self) -> list[Path]:
+        """Files whose change should trigger a rebuild during ``properdocs serve``."""
+
+        assert self._project_root is not None
+        result = self._git("ls-files", "--cached", "--others", "--exclude-standard")
+        if result.returncode == 0:
+            files = [self._project_root / line for line in result.stdout.splitlines() if line]
+        else:
+            files = [path for path in self._project_root.rglob("*") if path.is_file()]
+        output = self.output.resolve()
+        watched = [
+            path
+            for path in files
+            if output not in path.resolve().parents and ".git" not in path.parts
+        ]
+        refs = self._project_root / ".git" / "refs"
+        if refs.is_dir():
+            watched.extend(path for path in refs.rglob("*") if path.is_file())
+        return watched
+
+    def _fingerprint(self) -> tuple[tuple[str, int, int], ...]:
+        values: list[tuple[str, int, int]] = []
+        for path in self._watched_files():
+            try:
+                stat = path.stat()
+            except OSError:
+                continue
+            values.append((str(path), stat.st_mtime_ns, stat.st_size))
+        return tuple(sorted(values))
+
+    def on_pre_build(self, *, config) -> None:
+        del config
+        assert self._cpdocs is not None
+        fingerprint = self._fingerprint()
+        versions = Layout.for_output(self.output).versions
+        if self._serve_active and fingerprint == self._last_fingerprint and versions.is_dir():
+            return
+        try:
+            build_versions(
+                self._cpdocs,
+                output=self.output,
+                project_docs_root_depth=len(PurePosixPath(self.mount).parts),
+            )
+        except RuntimeError as error:
+            raise PluginError(f"cpdocs: {error}") from error
+        self._last_fingerprint = fingerprint
+        self._symbols = {}
+
+    def _symbol_pages(self, version: str) -> dict[tuple[str, ...], str]:
+        if version not in self._symbols:
+            path = Layout.for_output(self.output).versions / version / "symbols.json"
+            try:
+                names = json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                names = {}
+            self._symbols[version] = {
+                _symbol_key(name): str(target) for name, target in names.items()
+            }
+        return self._symbols[version]
+
+    def _locate(self, version: str, symbol: str) -> str | None:
+        return self._symbol_pages(version).get(_symbol_key(symbol))
+
+    def _versions_metadata(self) -> dict[str, object]:
+        path = Layout.for_output(self.output).versions / "versions.json"
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return {}
+
+    def on_page_markdown(self, markdown, page, config, files=None):
+        del config, files
+        assert self._cpdocs is not None
+        level = self._cpdocs.check_broken_references
+        missing: list[tuple[str, str]] = []
+        markdown = expand_versions_directive(
+            markdown,
+            page_dest_uri=page.file.dest_uri,
+            mount=self.mount,
+            metadata=self._versions_metadata(),
+        )
+        result = resolve_api_references(
+            markdown,
+            page_dest_uri=page.file.dest_uri,
+            mount=self.mount,
+            default_version=recorded_default_version(self.output),
+            locate=self._locate,
+            missing=missing,
+        )
+        if missing and level != "ignore":
+            listing = ", ".join(f"{symbol} ({version})" for version, symbol in missing)
+            message = f"cpdocs: {page.file.src_uri} references unknown API entities: {listing}"
+            if level == "fail":
+                raise PluginError(message)
+            _LOG.warning(message)
+        return result
+
+    def on_page_context(self, context, page, config, nav=None):
+        del nav
+        assert self._project_root is not None
+        repo_url = str(config.get("repo_url") or "").strip()
+        extra = config.get("extra", {}) or {}
+        ref = extra.get("cpdocs_source_ref")
+        context["cpdocs_source_url"] = None
+        context["cpdocs_edit_url"] = None
+        if not repo_url or not ref:
+            return context
+        source = Path(page.file.abs_src_path).resolve()
+        try:
+            relative_source = source.relative_to(self._project_root).as_posix()
+        except ValueError:
+            return context
+        provider = repository_provider(repo_url, extra)
+        context["cpdocs_source_url"] = source_url(repo_url, provider, str(ref), relative_source)
+        context["cpdocs_edit_url"] = edit_url(repo_url, provider, str(ref), relative_source)
+        return context
+
+    def on_post_build(self, *, config) -> None:
+        publish_api(
+            Layout.for_output(self.output).versions, Path(config["site_dir"]).resolve(), self.mount
+        )