cpdocs 0.2.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cpdocs
-Version: 0.2.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.2.0 → cpdocs-0.3.1}/docs/web/reference/cli.md

@@ -5,8 +5,8 @@ SPDX-License-Identifier: Apache-2.0
 # Command line
 
 ```text
-cpdocs build [--config docs/cpdocs.yml] [--output build] [--label main]
-cpdocs versions [--config docs/cpdocs.yml] [--output build]
+cpdocs build [--config docs/cpdocs.yml] [--output build] [--tmp-directory DIR] [--label main]
+cpdocs versions [--config docs/cpdocs.yml] [--output build] [--tmp-directory DIR]
 cpdocs manifest python feature-sets ...
 cpdocs manifest python build ...
 cpdocs rust feature-sets --source <project> --output <feature-sets.json>
@@ -26,5 +26,6 @@ declared Cargo feature is treated as a disjoint feature set and documented once;
 specific combinations can list them in `[package.metadata.cpdocs]`. `rust build` runs Cargo rustdoc
 with nightly JSON output and writes a normal cpdocs manifest.
 
-Feature-set inputs, manifests, scratch/build directories and command logs are kept below
-`<output>/cpdocs/work/<version>/feature-sets/`.
+By default, feature-set inputs, manifests, scratch/build directories and command logs are kept below
+`<output>/cpdocs/work/<version>/feature-sets/`. Pass `--tmp-directory DIR` to keep this workspace
+under `DIR/cpdocs/work/` while leaving rendered output under `<output>/cpdocs/`.

{cpdocs-0.2.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.2.0"
+__version__ = "0.3.1"

{cpdocs-0.2.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
@@ -47,13 +47,16 @@ _CONTAINER_KINDS = {"namespace", "package", "module"}
 
 @dataclasses.dataclass(frozen=True)
 class Layout:
-    """Directories below ``<output>/cpdocs``."""
+    """Published and temporary directories used by cpdocs."""
 
     root: Path
+    work_root: Path
 
     @classmethod
-    def for_output(cls, output: Path) -> Layout:
-        return cls(root=(output / "cpdocs").resolve())
+    def for_output(cls, output: Path, *, tmp_directory: Path | None = None) -> Layout:
+        root = (output / "cpdocs").resolve()
+        work_root = (tmp_directory.resolve() / "cpdocs" if tmp_directory else root)
+        return cls(root=root, work_root=work_root)
 
     @property
     def current(self) -> Path:
@@ -64,7 +67,7 @@ class Layout:
         return self.root / "versions"
 
     def work(self, ref: str) -> Path:
-        return self.root / "work" / ref.replace("/", "__")
+        return self.work_root / "work" / ref.replace("/", "__")
 
 
 
@@ -196,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 = (
@@ -208,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 = (
@@ -239,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]:
@@ -322,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)
 
@@ -424,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)
@@ -505,10 +584,11 @@ def build_current(
     output: Path,
     version: str = "main",
     project_docs_root_depth: int = 2,
+    tmp_directory: Path | None = None,
 ) -> ApiGraph:
     """Document the working tree into ``<output>/cpdocs/current``."""
 
-    layout = Layout.for_output(output)
+    layout = Layout.for_output(output, tmp_directory=tmp_directory)
     work = layout.work("current")
     graph = build_graph(
         config,
@@ -610,10 +690,11 @@ def build_versions(
     output: Path,
     project_docs_root_depth: int = 2,
     include_working_tree: bool = False,
+    tmp_directory: Path | None = None,
 ) -> list[str]:
     """Document the explicitly configured ``versions`` in order."""
 
-    layout = Layout.for_output(output)
+    layout = Layout.for_output(output, tmp_directory=tmp_directory)
     project_root = config.project_root.resolve()
     subdirectory = project_root.relative_to(_repository_root(project_root))
     selected = select_refs(project_root, config.versions)

{cpdocs-0.2.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.2.0 → cpdocs-0.3.1}/src/cpdocs/cli.py

@@ -34,6 +34,11 @@ def _parser() -> argparse.ArgumentParser:
             default=Path("build"),
             help="output root; cpdocs writes below <output>/cpdocs (default: build)",
         )
+        command.add_argument(
+            "--tmp-directory",
+            type=_path,
+            help="temporary workspace root; defaults to the output root",
+        )
         return command
 
     build = documentation("build", "document the working tree")
@@ -110,10 +115,15 @@ def main(argv: list[str] | None = None) -> int:
         else:
             config = load_config(arguments.config)
             output = arguments.output.resolve()
+            tmp_directory = (
+                arguments.tmp_directory.resolve() if arguments.tmp_directory is not None else None
+            )
             if arguments.command == "build":
-                build_current(config, output=output, version=arguments.label)
+                build_current(
+                    config, output=output, version=arguments.label, tmp_directory=tmp_directory
+                )
             else:
-                build_versions(config, output=output)
+                build_versions(config, output=output, tmp_directory=tmp_directory)
     except RuntimeError as error:
         parser.exit(1, f"cpdocs: error: {error}\n")
     return 0

{cpdocs-0.2.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.2.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.2.0 → cpdocs-0.3.1}/src/cpdocs/properdocs_plugin.py

@@ -44,6 +44,7 @@ class CpdocsPlugin(BasePlugin):
     config_scheme = (
         ("config", c.Type(str, default=str(DEFAULT_CONFIG))),
         ("output", c.Type(str, default="build")),
+        ("tmp_directory", c.Type(str, default="")),
         ("mount", c.Type(str, default="reference/api")),
         ("subsites", c.ListOfItems(c.Type(str), default=[])),
     )
@@ -69,6 +70,15 @@ class CpdocsPlugin(BasePlugin):
         path = Path(str(self.config.get("output", "build")))
         return path if path.is_absolute() else self._project_root / path
 
+    @property
+    def tmp_directory(self) -> Path | None:
+        assert self._project_root is not None
+        value = str(self.config.get("tmp_directory", "")).strip()
+        if not value:
+            return None
+        path = Path(value).expanduser()
+        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" or os.environ.get("_CPDOCS_SERVE_IN_SITU") == "1"
@@ -221,6 +231,7 @@ class CpdocsPlugin(BasePlugin):
                 output=self.output,
                 project_docs_root_depth=len(PurePosixPath(self.mount).parts),
                 include_working_tree=self._serve_active,
+                tmp_directory=self.tmp_directory,
             )
         except RuntimeError as error:
             raise PluginError(f"cpdocs: {error}") from error

{cpdocs-0.2.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.2.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.2.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",
@@ -153,3 +175,24 @@ def test_obsolete_cpdocs_cmake_placeholder_is_rejected(tmp_path: Path) -> None:
     )
     with pytest.raises(RuntimeError, match="cpdocs-cmake"):
         build_current(load_config(config), output=project / "build")
+
+
+def test_tmp_directory_separates_work_from_output(tmp_path, monkeypatch):
+    project = tmp_path / "project"
+    project.mkdir()
+    config_file = project / "cpdocs.yml"
+    config_file.write_text(
+        "contract: 3\nproject: demo\nlanguages: [python]\n"
+        "build:\n"
+        "  feature-sets: >-\n"
+        "    python -c \"import pathlib; pathlib.Path(r'{{output-file}}').write_text('[]')\"\n"
+        "  build: >-\n"
+        "    python -c \"import pathlib; pathlib.Path(r'{{output-file}}').write_text('[]')\"\n",
+        encoding="utf-8",
+    )
+    # Layout behavior is the contract under test; avoid coupling this regression to providers.
+    from cpdocs.build import Layout
+
+    layout = Layout.for_output(project / "build", tmp_directory=tmp_path / "scratch")
+    assert layout.root == (project / "build" / "cpdocs").resolve()
+    assert layout.work("main") == (tmp_path / "scratch" / "cpdocs" / "work" / "main").resolve()

cpdocs-0.2.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)]