cpdocs 0.2.0__tar.gz → 0.3.0__tar.gz

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

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

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

@@ -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("/", "__")
 
 
 
@@ -505,10 +508,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 +614,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.0}/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.0}/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.0}/test/test_build.py

@@ -153,3 +153,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()