cpdocs 0.3.0__tar.gz → 0.3.2__tar.gz

{cpdocs-0.3.0 → cpdocs-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cpdocs
-Version: 0.3.0
+Version: 0.3.2
 Summary: Semantic, versioned API documentation for C, C++, CUDA, HIP, Fortran, Python and Rust projects
 Project-URL: Source, https://github.com/ambhora/cpdocs
 Author-email: Jayesh Badwaik <j.badwaik@fz-juelich.de>

cpdocs-0.3.2/examples/fortran-basic/docs/api.md

@@ -0,0 +1,12 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# API reference
+
+The API reference is generated from the public Fortran module for every documented feature set.
+
+## Versions
+
+@apidocs-versions

{cpdocs-0.3.0 → cpdocs-0.3.2}/examples/fortran-basic/properdocs.yml

@@ -20,3 +20,4 @@ theme:
 
 nav:
   - Home: index.md
+  - API reference: api.md

{cpdocs-0.3.0 → cpdocs-0.3.2}/pyproject.toml

@@ -29,7 +29,7 @@ Source = "https://github.com/ambhora/cpdocs"
 cpdocs = "cpdocs.cli:main"
 
 [project.entry-points."properdocs.plugins"]
-cpdocs = "cpdocs.properdocs_plugin:CpdocsPlugin"
+cpdocs = "cpdocs.plugins.properdocs.plugin:CpdocsPlugin"
 
 [dependency-groups]
 dev = ["pytest>=8", "ruff>=0.8", "properdocs>=1.6.7", "mkdocs-materialx"]

{cpdocs-0.3.0 → cpdocs-0.3.2}/src/cpdocs/__init__.py

@@ -2,4 +2,4 @@
 # SPDX-License-Identifier: Apache-2.0
 """Language-neutral semantic API documentation generator."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"

{cpdocs-0.3.0 → cpdocs-0.3.2}/src/cpdocs/build.py

@@ -15,35 +15,24 @@ import dataclasses
 import fnmatch
 import json
 import os
-import re
 import shutil
 import subprocess
 import sys
 import tempfile
 from pathlib import Path, PurePosixPath
 
-from .clang_backend import extract_clang_graph
-from .config import CpdocsConfig, load_config
-from .contract import (
-    ContractError,
-    FeatureSetDeclaration,
-    FeatureSets,
-    Manifest,
-    UnitManifest,
-    read_feature_sets,
-    read_manifest,
-    write_feature_set,
-)
-from .fortran_backend import extract_fortran_graph
-from .html_renderer import render_html_site
-from .model import ApiGraph, merge_graphs
-from .python_backend import build_python_graph
-from .rust_backend import build_rust_graph
+from .config import CpdocsConfig
+from .contract import ContractError, UnitManifest
+from .languages import rendering_for
+from .languages.cpp.extract import extract_clang_graph
+from .languages.fortran.extract import extract_fortran_graph
+from .languages.python.extract import build_python_graph
+from .languages.rust.extract import build_rust_graph
+from .model import ApiGraph, merge_graphs, relative_source_path
+from .providers.contract import discover_feature_sets, resolve_manifest
+from .rendering.html import render_html_site
 from .versioning import SelectedRef, current_branch, select_refs
 
-_PLACEHOLDER = re.compile(r"\{\{([a-z][a-z0-9-]*)\}\}")
-_CONTAINER_KINDS = {"namespace", "package", "module"}
-
 
 @dataclasses.dataclass(frozen=True)
 class Layout:
@@ -71,113 +60,6 @@ class Layout:
 
 
 
-# --------------------------------------------------------------------------------------------------
-# Talking to the build system
-# --------------------------------------------------------------------------------------------------
-
-
-def _expand(command: str, values: dict[str, str], *, allowed: set[str], name: str) -> str:
-    placeholders = set(_PLACEHOLDER.findall(command))
-    unknown = sorted(placeholders - allowed)
-    if unknown:
-        raise RuntimeError(
-            f"cpdocs.yml: build.{name} uses unknown placeholders: {', '.join(unknown)}"
-        )
-    return _PLACEHOLDER.sub(lambda match: values[match.group(1)], command)
-
-
-def _run_command(
-    command: str,
-    *,
-    source: Path,
-    values: dict[str, str],
-    allowed: set[str],
-    name: str,
-    log: Path,
-) -> None:
-    expanded = _expand(command, values, allowed=allowed, name=name)
-    environment = dict(os.environ)
-    # Commands invoked from a source checkout should be able to use cpdocs' own helper CLI just as
-    # they can when cpdocs is installed.  This is only an execution-environment convenience; the
-    # build-system contract itself remains the JSON files and command placeholders.
-    package_root = str(Path(__file__).resolve().parents[1])
-    pythonpath = environment.get("PYTHONPATH")
-    environment["PYTHONPATH"] = package_root + (os.pathsep + pythonpath if pythonpath else "")
-    log.parent.mkdir(parents=True, exist_ok=True)
-    with log.open("w", encoding="utf-8") as stream:
-        stream.write("$ " + expanded + "\n")
-        stream.flush()
-        result = subprocess.run(
-            expanded,
-            cwd=source,
-            shell=True,
-            check=False,
-            text=True,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.STDOUT,
-            env=environment,
-        )
-        stream.write(result.stdout)
-    if result.returncode != 0:
-        raise RuntimeError(
-            f"build-system command failed (build.{name}):\n  {expanded}\n\n"
-            + result.stdout.rstrip()
-        )
-
-
-def discover_feature_sets(command: str, *, source: Path, work: Path) -> FeatureSets:
-    """Run ``build.feature-sets`` and read ``feature-sets.json``."""
-
-    directory = work / "feature-sets"
-    shutil.rmtree(directory, ignore_errors=True)
-    tmpdir = directory / "tmp"
-    tmpdir.mkdir(parents=True)
-    output = directory / "feature-sets.json"
-    _run_command(
-        command,
-        source=source.resolve(),
-        values={
-            "source": str(source.resolve()),
-            "tmpdir": str(tmpdir.resolve()),
-            "output-file": str(output.resolve()),
-            "python": sys.executable,
-        },
-        allowed={"source", "tmpdir", "output-file", "python"},
-        name="feature-sets",
-        log=directory / "log.txt",
-    )
-    return read_feature_sets(output)
-
-
-def resolve_manifest(
-    command: str, feature_set: FeatureSetDeclaration, *, source: Path, work: Path
-) -> Manifest:
-    """Run ``build.build`` once for one concrete feature set and read ``manifest.json``."""
-
-    directory = work / "feature-sets" / feature_set.key
-    shutil.rmtree(directory, ignore_errors=True)
-    tmpdir = directory / "tmp"
-    tmpdir.mkdir(parents=True)
-    feature_set_file = directory / "feature-set.json"
-    output = directory / "manifest.json"
-    write_feature_set(feature_set_file, feature_set)
-    _run_command(
-        command,
-        source=source.resolve(),
-        values={
-            "source": str(source.resolve()),
-            "tmpdir": str(tmpdir.resolve()),
-            "feature-set": str(feature_set_file.resolve()),
-            "output-file": str(output.resolve()),
-            "python": sys.executable,
-        },
-        allowed={"source", "tmpdir", "feature-set", "output-file", "python"},
-        name="build",
-        log=directory / "log.txt",
-    )
-    return read_manifest(output, source=source.resolve())
-
-
 # --------------------------------------------------------------------------------------------------
 # Extraction
 # --------------------------------------------------------------------------------------------------
@@ -199,8 +81,8 @@ def _browse_logical_path(
     try:
         return path.resolve().relative_to(project_root.resolve()).as_posix()
     except (OSError, ValueError):
-        # Generated files live outside the source checkout. Give them a stable logical home rather
-        # than leaking profile/build-directory paths into the published file hierarchy.
+        # Keep a stable internal key for files outside the checkout. This path is not presented to
+        # readers; rendering uses the semantic layout recorded in ``source_display_paths``.
         base = Path("_generated") / unit.id / category
         try:
             relative = (
@@ -211,11 +93,69 @@ def _browse_logical_path(
         return (base / relative).as_posix()
 
 
+def _semantic_display_path(path: Path, *, root: Path, generated: bool) -> str:
+    """Return the compiler-facing layout path shown in the file browser.
+
+    Manifest roots are semantic roots. A file below ``.../src/cuda/include`` is therefore shown
+    below ``include`` and a file below ``.../src/cuda/lib`` below ``lib``. Build-generated roots
+    use the same flattened layout under one ``_generated`` prefix.
+    """
+
+    try:
+        if root.is_dir():
+            relative = path.resolve().relative_to(root.resolve())
+            root_name = root.name
+        else:
+            relative = Path(path.name)
+            root_name = root.parent.name
+    except (OSError, ValueError):
+        relative = Path(path.name)
+        root_name = root.name if root.name != path.name else root.parent.name
+
+    base = Path("_generated") if generated else Path()
+    if root_name:
+        base /= root_name
+    return (base / relative).as_posix()
+
+
+def _api_display_paths(
+    unit: UnitManifest, graph: ApiGraph, *, project_root: Path
+) -> dict[str, str]:
+    """Map API source keys to their semantic include/module layout."""
+
+    values: dict[str, str] = {}
+    for api_root in unit.api:
+        root = api_root.path
+        if not root.is_dir():
+            continue
+        for path in sorted(root.rglob("*")):
+            if not path.is_file():
+                continue
+            try:
+                root_relative = path.resolve().relative_to(root.resolve()).as_posix()
+            except (OSError, ValueError):
+                root_relative = path.name
+            project_relative = relative_source_path(path, project_root)
+            logical = next(
+                (candidate for candidate in (root_relative, project_relative) if candidate in graph.sources),
+                None,
+            )
+            if logical is not None:
+                values.setdefault(
+                    logical,
+                    _semantic_display_path(
+                        path, root=root, generated=unit.generated or api_root.generated
+                    ),
+                )
+    return values
+
+
 def _collect_browse_files(
     unit: UnitManifest, *, project_root: Path
-) -> tuple[dict[str, str], list[str]]:
+) -> tuple[dict[str, str], list[str], dict[str, str]]:
     files: dict[str, str] = {}
     generated: list[str] = []
+    display_paths: dict[str, str] = {}
     # Public headers are already present in ``graph.sources`` after API extraction.  These roots
     # add implementation-only material without duplicating public headers in the file hierarchy.
     groups = (
@@ -242,9 +182,13 @@ def _collect_browse_files(
                     path, project_root=project_root, unit=unit, category=category, root=root
                 )
                 files.setdefault(logical, content)
+                display_paths.setdefault(
+                    logical,
+                    _semantic_display_path(path, root=root, generated=unit.generated),
+                )
                 if unit.generated and logical not in generated:
                     generated.append(logical)
-    return files, generated
+    return files, generated, display_paths
 
 
 def _generated_sources(unit: UnitManifest, graph: ApiGraph) -> list[str]:
@@ -325,6 +269,11 @@ def _merge_metadata(target: dict[str, object], source: dict[str, object]) -> Non
             existing = target.setdefault(key, [])
             assert isinstance(existing, list)
             existing.extend(item for item in value if item not in existing)
+        elif isinstance(value, dict):
+            existing = target.setdefault(key, {})
+            assert isinstance(existing, dict)
+            for item_key, item_value in value.items():
+                existing.setdefault(item_key, item_value)
         else:
             target.setdefault(key, value)
 
@@ -374,7 +323,8 @@ def _check_undocumented(graph: ApiGraph, level: str) -> None:
     missing = sorted(
         entity.qualified_name
         for entity in graph.entities.values()
-        if entity.kind not in _CONTAINER_KINDS and not entity.documentation.strip()
+        if entity.kind not in rendering_for(entity.language).container_kinds
+        and not entity.documentation.strip()
     )
     if not missing:
         return
@@ -427,9 +377,18 @@ def build_graph(
                 work=work / "feature-sets" / feature_set.key,
                 config=config,
             )
-            browse_files, generated_files = _collect_browse_files(unit, project_root=source)
+            display_paths = unit_graph.metadata.setdefault("source_display_paths", {})
+            assert isinstance(display_paths, dict)
+            for path, display in _api_display_paths(unit, unit_graph, project_root=source).items():
+                display_paths.setdefault(path, display)
+
+            browse_files, generated_files, browse_display_paths = _collect_browse_files(
+                unit, project_root=source
+            )
             for path, content in browse_files.items():
                 unit_graph.files.setdefault(path, content)
+            for path, display in browse_display_paths.items():
+                display_paths.setdefault(path, display)
             if generated_files:
                 existing = unit_graph.metadata.setdefault("generated_files", [])
                 assert isinstance(existing, list)
@@ -688,7 +647,6 @@ __all__ = [
     "build_current",
     "build_graph",
     "build_versions",
-    "cmake_module",
     "discover_feature_sets",
     "recorded_default_version",
     "resolve_manifest",

{cpdocs-0.3.0 → cpdocs-0.3.2}/src/cpdocs/cli.py

@@ -10,10 +10,10 @@ from pathlib import Path
 from . import __version__
 from .build import build_current, build_versions
 from .config import DEFAULT_CONFIG, load_config
-from .python_manifest import write_feature_sets as write_python_feature_sets
-from .python_manifest import write_manifest as write_python_manifest
-from .rust_manifest import write_feature_sets as write_rust_feature_sets
-from .rust_manifest import write_manifest as write_rust_manifest
+from .providers.python import write_feature_sets as write_python_feature_sets
+from .providers.python import write_manifest as write_python_manifest
+from .providers.cargo import write_feature_sets as write_rust_feature_sets
+from .providers.cargo import write_manifest as write_rust_manifest
 
 
 def _path(value: str) -> Path:

{cpdocs-0.3.0 → cpdocs-0.3.2}/src/cpdocs/contract.py

@@ -173,16 +173,16 @@ def read_manifest(path: Path, *, source: Path) -> Manifest:
                 )
             )
 
-        def paths(field: str) -> tuple[Path, ...]:
+        def paths(field: str, *, data: dict[str, Any], where: str) -> tuple[Path, ...]:
             return tuple(
                 _path(item, source)
                 for item in _string_tuple(data.get(field, []), f"{where}.{field}", path)
             )
 
-        headers = paths("headers")
-        sources = paths("sources")
-        modules = paths("modules")
-        executables = paths("executables")
+        headers = paths("headers", data=data, where=where)
+        sources = paths("sources", data=data, where=where)
+        modules = paths("modules", data=data, where=where)
+        executables = paths("executables", data=data, where=where)
         generated = bool(data.get("generated", False))
 
         parse: ParseOptions | None = None

cpdocs-0.3.2/src/cpdocs/languages/__init__.py

@@ -0,0 +1,138 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+"""Programming-language adapters for extraction and presentation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .base import LanguageRendering
+from .cpp.render import RENDERING as CPP
+from .fortran.render import RENDERING as FORTRAN
+from .python.render import RENDERING as PYTHON
+from .rust.render import RENDERING as RUST
+
+_RENDERINGS = {
+    "c": CPP,
+    "cpp": CPP,
+    "cuda": CPP,
+    "hip": CPP,
+    "fortran": FORTRAN,
+    "python": PYTHON,
+    "rust": RUST,
+}
+
+_LANGUAGE_LABELS = {
+    "c": "C",
+    "cpp": "C++",
+    "cuda": "CUDA",
+    "hip": "HIP",
+    "fortran": "Fortran",
+    "python": "Python",
+    "rust": "Rust",
+}
+
+_KIND_LABELS = {
+    "namespace": "namespace",
+    "module": "module",
+    "package": "package",
+    "class": "class",
+    "struct": "struct",
+    "derived_type": "derived type",
+    "union": "union",
+    "enum": "enum",
+    "trait": "trait",
+    "protocol": "protocol",
+    "type_alias": "type alias",
+    "concept": "concept",
+    "function": "function",
+    "subroutine": "subroutine",
+    "method": "method",
+    "constructor": "constructor",
+    "property": "property",
+    "attribute": "attribute",
+    "variable": "variable",
+    "constant": "constant",
+    "macro": "macro",
+    "deduction_guide": "deduction guide",
+}
+
+_KIND_MARKERS = {
+    "namespace": "N",
+    "module": "M",
+    "package": "P",
+    "class": "C",
+    "struct": "S",
+    "derived_type": "T",
+    "union": "U",
+    "enum": "E",
+    "trait": "T",
+    "protocol": "P",
+    "function": "F",
+    "subroutine": "F",
+    "method": "F",
+    "constructor": "F",
+    "type_alias": "T",
+    "variable": "V",
+    "attribute": "A",
+    "property": "P",
+    "constant": "C",
+    "macro": "D",
+    "concept": "K",
+    "deduction_guide": "G",
+}
+
+
+def rendering_for(language: str) -> LanguageRendering:
+    """Return rendering semantics for one programming language."""
+
+    try:
+        return _RENDERINGS[language]
+    except KeyError as error:
+        raise ValueError(f"unsupported API language: {language}") from error
+
+
+def language_label(language: str) -> str:
+    return _LANGUAGE_LABELS.get(language, language)
+
+
+def kind_label(kind: str, language: str | None = None) -> str:
+    if language in _RENDERINGS:
+        specific = _RENDERINGS[language].kind_labels.get(kind)
+        if specific is not None:
+            return specific
+    return _KIND_LABELS.get(kind, kind.replace("_", " "))
+
+
+def kind_marker(kind: str, language: str | None = None) -> str:
+    if language in _RENDERINGS:
+        specific = _RENDERINGS[language].kind_markers.get(kind)
+        if specific is not None:
+            return specific
+    return _KIND_MARKERS.get(kind, "·")
+
+
+def source_language(path: str) -> str:
+    suffix = Path(path).suffix.casefold()
+    if suffix in {".cu", ".cuh"}:
+        return "cuda"
+    if suffix == ".hip":
+        return "hip"
+    if suffix in {".c"}:
+        return "c"
+    if suffix in {".h", ".hh", ".hpp", ".hxx", ".cc", ".cpp", ".cxx"}:
+        return "cpp"
+    for language in ("fortran", "python", "rust"):
+        if suffix in _RENDERINGS[language].source_suffixes:
+            return language
+    return "text"
+
+
+__all__ = [
+    "LanguageRendering",
+    "kind_label",
+    "kind_marker",
+    "language_label",
+    "rendering_for",
+    "source_language",
+]

cpdocs-0.3.2/src/cpdocs/languages/base.py

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+"""Language-specific presentation contract used by generic renderers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from ..model import ApiEntity, ApiSignature
+
+
+@dataclass(frozen=True)
+class LanguageRendering:
+    """Rendering rules that belong to a programming language, not to HTML."""
+
+    separator: str
+    container_kinds: frozenset[str]
+    class_like_kinds: frozenset[str]
+    type_page_kinds: frozenset[str]
+    type_like_kinds: frozenset[str]
+    function_kinds: frozenset[str]
+    member_value_kinds: frozenset[str]
+    source_suffixes: frozenset[str]
+    kind_markers: dict[str, str]
+    kind_labels: dict[str, str]
+    signature_spelling: Callable[[ApiEntity, ApiSignature], str]
+    entity_declaration: Callable[[ApiEntity], str]
+    member_summary: Callable[[ApiEntity], str]
+    member_group: Callable[[ApiEntity], str | None]
+
+
+def parameter_spelling(signature: ApiSignature) -> str:
+    """Render conventional typed parameters used by C-family, Fortran and Rust APIs."""
+
+    values: list[str] = []
+    for parameter in signature.parameters:
+        value = parameter.type or parameter.name
+        if parameter.name and parameter.type:
+            value += f" {parameter.name}"
+        if parameter.default is not None:
+            value += f" = {parameter.default}"
+        values.append(value)
+    return ", ".join(values)
+
+
+def assigned_property(entity: ApiEntity) -> str:
+    """Return an ``= value`` property without its marker."""
+
+    return next((value[2:] for value in entity.properties if value.startswith("= ")), "")
+
+
+def typed_property(entity: ApiEntity, *, ignored: frozenset[str] = frozenset()) -> str:
+    """Return the first property that represents a type rather than an assignment/flag."""
+
+    return next(
+        (
+            value
+            for value in entity.properties
+            if not value.startswith("=") and value not in ignored
+        ),
+        "",
+    )

cpdocs-0.3.2/src/cpdocs/languages/cpp/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+"""C-family extraction and rendering."""
+
+from .extract import extract_clang_graph
+from .render import RENDERING
+
+__all__ = ["RENDERING", "extract_clang_graph"]