cpdocs 0.3.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cpdocs
-Version: 0.3.0
+Version: 0.3.1
 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.0 → cpdocs-0.3.1}/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.1"

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

@@ -36,7 +36,7 @@ from .contract import (
 )
 from .fortran_backend import extract_fortran_graph
 from .html_renderer import render_html_site
-from .model import ApiGraph, merge_graphs
+from .model import ApiGraph, merge_graphs, relative_source_path
 from .python_backend import build_python_graph
 from .rust_backend import build_rust_graph
 from .versioning import SelectedRef, current_branch, select_refs
@@ -199,8 +199,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 +211,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 +300,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 +387,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)
 
@@ -427,9 +494,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)

{cpdocs-0.3.0 → cpdocs-0.3.1}/src/cpdocs/clang_backend.py

@@ -21,6 +21,7 @@ from pathlib import Path
 
 from .contract import ParseOptions
 from .model import (
+    ApiAttribute,
     ApiEntity,
     ApiGraph,
     ApiParameter,
@@ -351,10 +352,79 @@ def _qualifiers(node: dict[str, object]) -> tuple[str, ...]:
     return tuple(values)
 
 
-def _signature(node: dict[str, object]) -> ApiSignature:
+_ATTRIBUTE_NAMES = {
+    "WarnUnusedResultAttr": "nodiscard",
+    "DeprecatedAttr": "deprecated",
+    "UnusedAttr": "maybe_unused",
+    "CXX11NoReturnAttr": "noreturn",
+    "NoUniqueAddressAttr": "no_unique_address",
+    "CarriesDependencyAttr": "carries_dependency",
+    "LikelyAttr": "likely",
+    "UnlikelyAttr": "unlikely",
+}
+
+
+def _attribute_name(node: dict[str, object]) -> str:
+    kind = str(node.get("kind", ""))
+    if kind in _ATTRIBUTE_NAMES:
+        return _ATTRIBUTE_NAMES[kind]
+    if not kind.endswith("Attr"):
+        return ""
+    stem = kind[:-4]
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", stem).lower()
+
+
+def _attribute_spelling(node: dict[str, object], path: Path | None) -> str:
+    """Recover the complete ``[[...]]`` specifier containing one Clang Attr node."""
+
+    if path is None:
+        return ""
+    offsets = _range_offsets(node)
+    if offsets is None:
+        return ""
+    data = _SOURCE_BYTES.get(path)
+    if data is None:
+        try:
+            data = path.read_bytes()
+        except OSError:
+            return ""
+        _SOURCE_BYTES[path] = data
+    start, stop = offsets
+    left = data.rfind(b"[[", max(0, start - 2048), start + 1)
+    if left < 0:
+        return ""
+    right = data.find(b"]]", left + 2, min(len(data), stop + 2048))
+    if right < 0 or not (left <= start and stop <= right + 2):
+        return ""
+    return re.sub(r"\s+", " ", data[left : right + 2].decode("utf-8", errors="replace")).strip()
+
+
+def _attributes(node: dict[str, object], path: Path | None) -> tuple[ApiAttribute, ...]:
+    children = node.get("inner")
+    if not isinstance(children, list):
+        return ()
+    values: list[ApiAttribute] = []
+    for child in children:
+        if not isinstance(child, dict) or not str(child.get("kind", "")).endswith("Attr"):
+            continue
+        name = _attribute_name(child)
+        if not name:
+            continue
+        attribute = ApiAttribute(name=name, spelling=_attribute_spelling(child, path))
+        if attribute not in values:
+            values.append(attribute)
+    return tuple(values)
+
+
+def _signature(node: dict[str, object], path: Path | None) -> ApiSignature:
     parameters = _parameters(node)
     qualifiers = _qualifiers(node)
-    return ApiSignature(parameters=parameters, returns=_return_type(node), qualifiers=qualifiers)
+    return ApiSignature(
+        parameters=parameters,
+        returns=_return_type(node),
+        qualifiers=qualifiers,
+        attributes=_attributes(node, path),
+    )
 
 
 # --------------------------------------------------------------------------------------------------
@@ -704,7 +774,7 @@ def _walk_ast(
             parent=parent_entity.id if parent_entity else None,
             signatures=[
                 replace(
-                    _signature(node),
+                    _signature(node, path),
                     template=template_header,
                     documentation=_attached_comment(node),
                     source=_location(node, path, project_root, public_roots),

{cpdocs-0.3.0 → cpdocs-0.3.1}/src/cpdocs/html_renderer.py

@@ -137,7 +137,13 @@ def _entity_href(source: Path, entity: ApiEntity, graph: ApiGraph) -> str:
 
 
 def _display_source_path(source_path: str, graph: ApiGraph) -> str:
-    """Return the source path shown to readers while preserving the real repository path for links."""
+    """Return the semantic path shown to readers while preserving internal source keys for links."""
+    display_paths = graph.metadata.get("source_display_paths", {})
+    if isinstance(display_paths, dict):
+        value = display_paths.get(source_path)
+        if isinstance(value, str) and value:
+            return value
+
     source_root = str(graph.metadata.get("source_root") or "").strip("/")
     logical = PurePosixPath(source_path)
     if not source_root:
@@ -610,7 +616,15 @@ def _signature_card(
     declaration = _highlight_declaration(
         spelling, entity.language, entity=entity, graph=graph, document_path=document
     )
-    properties = list(dict.fromkeys([*entity.properties, *signature.qualifiers]))
+    properties = list(
+        dict.fromkeys(
+            [
+                *entity.properties,
+                *signature.qualifiers,
+                *(attribute.name for attribute in signature.attributes),
+            ]
+        )
+    )
     rows = []
     if properties:
         rows.append(

{cpdocs-0.3.0 → cpdocs-0.3.1}/src/cpdocs/model.py

@@ -24,11 +24,20 @@ class ApiParameter:
     kind: str = ""
 
 
+@dataclass(frozen=True)
+class ApiAttribute:
+    """One source-level attribute attached to an API declaration."""
+
+    name: str
+    spelling: str = ""
+
+
 @dataclass(frozen=True)
 class ApiSignature:
     parameters: tuple[ApiParameter, ...] = ()
     returns: str = ""
     qualifiers: tuple[str, ...] = ()
+    attributes: tuple[ApiAttribute, ...] = ()
     spelling: str = ""
     template: str = ""
     # Documentation and location of this overload; not part of its identity.

{cpdocs-0.3.0 → cpdocs-0.3.1}/src/cpdocs/render.py

@@ -631,8 +631,12 @@ def _signature_spelling(entity: ApiEntity, signature: ApiSignature) -> str:
 
 
 def _plain_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 signature.spelling
+        return f"{attribute_prefix} {signature.spelling}".strip()
     parameters = _parameter_spelling(signature, entity.language)
     if entity.language == "python":
         prefix = "async def" if "async" in signature.qualifiers else "def"
@@ -656,7 +660,8 @@ def _plain_signature_spelling(entity: ApiEntity, signature: ApiSignature) -> str
     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 ""
-    return f"{prefix}{result}{entity.qualified_name}({parameters}){suffix}".strip()
+    declaration = f"{prefix}{result}{entity.qualified_name}({parameters}){suffix}".strip()
+    return f"{attribute_prefix} {declaration}".strip()
 
 
 def _entity_declaration(entity: ApiEntity) -> str:

{cpdocs-0.3.0 → cpdocs-0.3.1}/test/test_api_reference.py

@@ -13,6 +13,7 @@ from cpdocs.clang_backend import extract_clang_graph
 from cpdocs.contract import ParseOptions
 from cpdocs.html_renderer import render_html_site
 from cpdocs.model import (
+    ApiAttribute,
     ApiEntity,
     ApiGraph,
     ApiParameter,
@@ -37,11 +38,11 @@ def test_cpp_semantic_profiles_merge_conditional_api(tmp_path: Path) -> None:
 #ifdef USE_CUDA
 /// Active backend.
 #define DICE_BACKEND \"cuda\"
-namespace dice { struct cuda_view {}; void foo(cuda_view); }
+namespace dice { struct cuda_view {}; void foo(cuda_view); [[nodiscard]] int backend_name(); }
 #else
 /// Active backend.
 #define DICE_BACKEND \"cpu\"
-namespace dice { struct cpu_view {}; void foo(cpu_view); }
+namespace dice { struct cpu_view {}; void foo(cpu_view); [[nodiscard]] int backend_name(); }
 #endif
 class visible { public: void yes(); private: void no(); };
 """,
@@ -76,6 +77,10 @@ class visible { public: void yes(); private: void no(); };
     foo = merged.entities[stable_entity_id("cpp", "function", "dice::foo")]
     assert {signature.compact for signature in foo.signatures} == {"(cpu_view)", "(cuda_view)"}
     assert set(foo.feature_sets) == {"cpu", "cuda"}
+    backend_name = merged.entities[stable_entity_id("cpp", "function", "dice::backend_name")]
+    assert backend_name.signatures[0].attributes == (
+        ApiAttribute(name="nodiscard", spelling="[[nodiscard]]"),
+    )
     assert stable_entity_id("cpp", "method", "visible::yes") in merged.entities
     assert stable_entity_id("cpp", "method", "visible::no") not in merged.entities
 
@@ -206,7 +211,11 @@ def test_renderer_generates_standalone_code_oriented_html_site(tmp_path: Path) -
         qualified_name="dice::foo",
         parent=namespace.id,
         signatures=[
-            ApiSignature(parameters=(ApiParameter("value", "int"),), returns="void"),
+            ApiSignature(
+                parameters=(ApiParameter("value", "int"),),
+                returns="void",
+                attributes=(ApiAttribute(name="nodiscard", spelling="[[nodiscard]]"),),
+            ),
             ApiSignature(parameters=(ApiParameter("value", "float"),), returns="void"),
         ],
         documentation=(
@@ -315,6 +324,8 @@ def test_renderer_generates_standalone_code_oriented_html_site(tmp_path: Path) -
     page = html_page(entity_document(function)).read_text(encoding="utf-8")
     assert '<article class="api-signature-card"' in page
     assert "foo(int)" in page
+    assert page.count("nodiscard") >= 2
+    assert "<span>nodiscard</span>" in page
     assert "Available in feature sets" in page
     assert "<code>cpu</code>" in page
     assert "<strong>Related:</strong>" in page

{cpdocs-0.3.0 → cpdocs-0.3.1}/test/test_build.py

@@ -10,7 +10,7 @@ from pathlib import Path
 import pytest
 
 from conftest import fake_project, git, init_repository
-from cpdocs.build import build_current, build_versions
+from cpdocs.build import _semantic_display_path, build_current, build_versions
 from cpdocs.cli import main
 from cpdocs.config import load_config
 from cpdocs.model import stable_entity_id
@@ -27,6 +27,28 @@ def _no_ci_branch(monkeypatch: pytest.MonkeyPatch) -> None:
         monkeypatch.delenv(variable, raising=False)
 
 
+def test_semantic_file_layout_flattens_manifest_roots(tmp_path: Path) -> None:
+    include = tmp_path / "src" / "cuda" / "include"
+    library = tmp_path / "src" / "cuda" / "lib"
+    header = include / "kprof" / "cuda.hpp"
+    source = library / "kprof" / "synchronize.cu"
+    header.parent.mkdir(parents=True)
+    source.parent.mkdir(parents=True)
+    header.write_text("#pragma once\n", encoding="utf-8")
+    source.write_text("// source\n", encoding="utf-8")
+
+    assert _semantic_display_path(header, root=include, generated=False) == "include/kprof/cuda.hpp"
+    assert _semantic_display_path(source, root=library, generated=False) == "lib/kprof/synchronize.cu"
+    assert (
+        _semantic_display_path(header, root=include, generated=True)
+        == "_generated/include/kprof/cuda.hpp"
+    )
+    assert (
+        _semantic_display_path(source, root=library, generated=True)
+        == "_generated/lib/kprof/synchronize.cu"
+    )
+
+
 def test_build_runs_feature_sets_once_then_build_once_per_feature_set(tmp_path: Path) -> None:
     project = fake_project(
         tmp_path / "p",

cpdocs-0.3.0/src/cpdocs/html_renderer.py.rej

@@ -1,12 +0,0 @@
-diff a/src/cpdocs/html_renderer.py b/src/cpdocs/html_renderer.py	(rejected hunks)
-@@ -698,7 +698,9 @@ def _namespace_page(
-         label = child.member_label
-         body.append(
-             '<li>' + _kind_badge(child.kind)
--            + f'<a href="{html.escape(_entity_href(document, child, graph))}">{html.escape(label)}</a></li>'
-+            + f'<a href="{html.escape(_entity_href(document, child, graph))}">{html.escape(label)}</a>'
-+            + _language_badge(child)
-+            + '</li>'
-         )
-     body.extend(["</ul>", _availability(entity, graph, document), "</section>"])
-     return "".join(body), [("Members", "members", 1)]