cpdocs 0.3.1__tar.gz → 0.3.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cpdocs
-Version: 0.3.1
+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.1 → 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.1 → 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.1 → 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.1"
+__version__ = "0.3.2"

{cpdocs-0.3.1 → 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 .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 .python_backend import build_python_graph
-from .rust_backend import build_rust_graph
+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
 # --------------------------------------------------------------------------------------------------
@@ -441,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
@@ -764,7 +647,6 @@ __all__ = [
     "build_current",
     "build_graph",
     "build_versions",
-    "cmake_module",
     "discover_feature_sets",
     "recorded_default_version",
     "resolve_manifest",

{cpdocs-0.3.1 → 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.1 → 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"]

cpdocs-0.3.1/src/cpdocs/clang_backend.py → cpdocs-0.3.2/src/cpdocs/languages/cpp/extract.py

@@ -19,8 +19,8 @@ from dataclasses import replace
 from functools import lru_cache
 from pathlib import Path
 
-from .contract import ParseOptions
-from .model import (
+from ...contract import ParseOptions
+from ...model import (
     ApiAttribute,
     ApiEntity,
     ApiGraph,

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

@@ -0,0 +1,125 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+"""C-family presentation rules for C, C++, CUDA and HIP."""
+
+from __future__ import annotations
+
+from ...model import ApiEntity, ApiSignature
+from ..base import (
+    LanguageRendering,
+    assigned_property,
+    parameter_spelling,
+    typed_property,
+)
+
+
+def entity_declaration(entity: ApiEntity) -> str:
+    if entity.declaration:
+        return entity.declaration
+    if entity.kind == "namespace":
+        value = f"namespace {entity.qualified_name}"
+    elif entity.kind in {"class", "struct", "union"}:
+        bases = f" : {', '.join(entity.bases)}" if entity.bases else ""
+        value = f"{entity.kind} {entity.qualified_name}{bases}"
+    elif entity.kind == "enum":
+        scoped = " class" if "scoped" in entity.properties else ""
+        value = f"enum{scoped} {entity.qualified_name}"
+    elif entity.kind == "type_alias":
+        value = f"using {entity.qualified_name} = {assigned_property(entity)}".rstrip()
+    elif entity.kind in {"attribute", "variable", "constant"}:
+        type_name = typed_property(entity)
+        assigned = assigned_property(entity)
+        value = f"{type_name} {entity.qualified_name}".strip()
+        if assigned:
+            value += f" = {assigned}"
+    elif entity.kind == "concept":
+        value = f"concept {entity.qualified_name}"
+    elif entity.kind == "macro" and entity.signatures:
+        value = entity.signatures[0].spelling or entity.name
+    else:
+        value = entity.qualified_name
+    return f"{entity.template}\n{value}" if entity.template else value
+
+
+def signature_spelling(entity: ApiEntity, signature: ApiSignature) -> str:
+    attribute_spellings = list(
+        dict.fromkeys(attribute.spelling for attribute in signature.attributes if attribute.spelling)
+    )
+    attribute_prefix = " ".join(attribute_spellings)
+    if signature.spelling:
+        return f"{attribute_prefix} {signature.spelling}".strip()
+
+    parameters = parameter_spelling(signature)
+    prefix_values = [
+        value
+        for value in entity.properties
+        if value in {"inline", "constexpr", "consteval", "static", "virtual"}
+    ]
+    prefix = (" ".join(prefix_values) + " ") if prefix_values else ""
+    result = (signature.returns + " ") if signature.returns else ""
+    suffix_values = [value for value in signature.qualifiers if value not in prefix_values]
+    suffix = (" " + " ".join(suffix_values)) if suffix_values else ""
+    declaration = f"{prefix}{result}{entity.qualified_name}({parameters}){suffix}".strip()
+    return f"{attribute_prefix} {declaration}".strip()
+
+
+def member_summary(entity: ApiEntity) -> str:
+    if entity.kind in {"attribute", "variable", "constant"}:
+        type_name = typed_property(entity)
+        assigned = assigned_property(entity)
+        value = f"{type_name} {entity.name}".strip()
+        return value + (f" = {assigned}" if assigned else "")
+    if entity.kind == "type_alias":
+        value = f"using {entity.name} = {assigned_property(entity)}".rstrip()
+        return f"{entity.template}\n{value}" if entity.template else value
+    if entity.kind in {"class", "struct", "union", "enum"}:
+        return f"{entity.kind} {entity.name}"
+    return entity.name
+
+
+def member_group(entity: ApiEntity) -> str | None:
+    if entity.kind in {"class", "struct", "union", "enum", "type_alias", "concept"}:
+        return "Public Types"
+    if entity.kind == "deduction_guide":
+        return "Deduction Guides"
+    if entity.kind in {"function", "method", "constructor"}:
+        return "Public Functions"
+    if entity.kind in {"attribute", "variable", "constant"}:
+        return "Public Members"
+    return None
+
+
+RENDERING = LanguageRendering(
+    separator="::",
+    container_kinds=frozenset({"namespace"}),
+    class_like_kinds=frozenset({"class", "struct", "union"}),
+    type_page_kinds=frozenset({"class", "struct", "union", "enum"}),
+    type_like_kinds=frozenset({"class", "struct", "union", "enum", "type_alias", "concept"}),
+    function_kinds=frozenset({"function", "method", "constructor", "deduction_guide"}),
+    member_value_kinds=frozenset({"attribute", "variable", "constant"}),
+    source_suffixes=frozenset(
+        {".h", ".hh", ".hpp", ".hxx", ".c", ".cc", ".cpp", ".cxx", ".cu", ".cuh", ".hip"}
+    ),
+    kind_markers={
+        "namespace": "N",
+        "class": "C",
+        "struct": "S",
+        "union": "U",
+        "enum": "E",
+        "function": "F",
+        "method": "F",
+        "constructor": "F",
+        "type_alias": "T",
+        "variable": "V",
+        "attribute": "A",
+        "constant": "C",
+        "macro": "D",
+        "concept": "K",
+        "deduction_guide": "G",
+    },
+    kind_labels={"deduction_guide": "deduction guide", "type_alias": "type alias"},
+    signature_spelling=signature_spelling,
+    entity_declaration=entity_declaration,
+    member_summary=member_summary,
+    member_group=member_group,
+)

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

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

cpdocs-0.3.1/src/cpdocs/fortran_backend.py → cpdocs-0.3.2/src/cpdocs/languages/fortran/extract.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
-from .model import (
+from ...model import (
     ApiEntity,
     ApiGraph,
     ApiParameter,