cpdocs 0.3.7__tar.gz → 0.3.9__tar.gz

cpdocs-0.3.9/.github/workflows/docs-tag-rebuild.yml

@@ -0,0 +1,59 @@
+# --------------------------------------------------------------------------------------------------
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# --------------------------------------------------------------------------------------------------
+name: historical tag documentation rebuild
+
+# GitHub loads push workflows from the pushed tag. Older tags carry the original
+# documentation workflow, which attempts to run the old cpdocs implementation
+# against the current branch. This workflow lives on the default branch and is
+# triggered when an old documentation run completes, even if that run failed.
+on:
+  workflow_run:
+    workflows: [documentation]
+    types: [completed]
+
+permissions:
+  contents: read
+
+jobs:
+  rebuild:
+    if: github.event.workflow_run.event == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          fetch-depth: 0
+
+      - name: Detect legacy tag workflow
+        id: legacy
+        env:
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          # A branch push (or a PR) must not trigger another docs build.
+          if ! git tag --points-at "$HEAD_SHA" | grep -q .; then
+            exit 0
+          fi
+
+          # Current tagged workflows already dispatch a default-branch build.
+          # Avoid dispatching a duplicate for those tags.
+          if git show "$HEAD_SHA:.github/workflows/docs.yml" 2>/dev/null \
+              | grep -q 'rebuild-for-tag:'; then
+            exit 0
+          fi
+
+          echo 'rebuild=true' >> "$GITHUB_OUTPUT"
+
+      - name: Build tagged API from the current documentation tool
+        if: steps.legacy.outputs.rebuild == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          gh workflow run docs.yml \
+            --repo "$GITHUB_REPOSITORY" \
+            --ref "$DEFAULT_BRANCH"

{cpdocs-0.3.7 → cpdocs-0.3.9}/PKG-INFO

@@ -1,16 +1,15 @@
 Metadata-Version: 2.5
 Name: cpdocs
-Version: 0.3.7
+Version: 0.3.9
 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>
 License-Expression: Apache-2.0
 Requires-Python: >=3.11
+Requires-Dist: keyso
 Requires-Dist: markdown-it-py>=3
 Requires-Dist: pygments>=2.17
 Requires-Dist: pyyaml>=6
-Provides-Extra: properdocs
-Requires-Dist: properdocs>=1.6.7; extra == 'properdocs'
 Description-Content-Type: text/markdown
 
 <!--
@@ -35,6 +34,56 @@ cpdocs versions       # document the configured versions
 properdocs build      # project website with the versioned API mounted
 ```
 
+## Language configurations
+
+The optional `languages` field in `docs/cpdocs.yml` is a [Keyso configuration
+space](https://ambhora.github.io/keyso/language/syntax/). cpdocs expands it using pykeyso,
+then runs `build.feature-sets` once per concrete configuration and `build.build` once per
+feature set discovered for that configuration. Both command templates receive dotted placeholders
+from the resulting nested dictionaries, such as `{{cxx.standard}}`, `{{c.standard}}`,
+`{{fortran.standard}}`, `{{python.version}}`, or `{{rust.edition}}`. The build system decides
+how to apply each value; cpdocs does not translate them into compiler flags.
+
+```yaml
+languages:
+  _product:
+    - cxx:
+        _nested:
+          standard: [17, 20, 23]
+    - python:
+        _nested:
+          version: ["3.11", "3.12"]
+
+build:
+  feature-sets: >-
+    cmake -S "{{source}}" -B "{{tmpdir}}"
+    -DCMAKE_CXX_STANDARD="{{cxx.standard}}"
+    -DPROJECT_FEATURE_SETS_OUTPUT="{{output-file}}"
+  build: >-
+    cmake -S "{{source}}" -B "{{tmpdir}}"
+    -DCMAKE_CXX_STANDARD="{{cxx.standard}}"
+    -DPROJECT_FEATURE_SET="{{feature-set}}"
+    -DPROJECT_CPDOCS_OUTPUT="{{output-file}}"
+    && cmake --build "{{tmpdir}}" --target project.cpdocs
+```
+
+Use `_set` for explicitly paired combinations rather than the `_product` Cartesian product:
+
+```yaml
+languages:
+  _set:
+    - cxx: {standard: 17}
+      python: {version: "3.11"}
+    - cxx: {standard: 23}
+      python: {version: "3.12"}
+```
+
+Each concrete configuration has its own work directory. The merged API records both the
+language configuration and feature set in symbol availability, including overload signatures.
+If `languages` is omitted, cpdocs performs the original single build configuration, and the
+existing `{{source}}`, `{{tmpdir}}`, `{{output-file}}`, `{{feature-set}}`, and `{{python}}`
+placeholders continue to work unchanged.
+
 The configuration lives in `docs/cpdocs.yml`, the API introduction in `docs/api/index.md` and the
 ProperDocs pages in `docs/web`. The documentation starts at `docs/web/index.md`; the `examples/`
 directory holds standalone projects that the test suite builds.

{cpdocs-0.3.7 → cpdocs-0.3.9}/docs/cpdocs.yml

@@ -13,7 +13,7 @@ build:
     --source "{{source}}" --feature-set "{{feature-set}}" --output "{{output-file}}"
     --package cpdocs --package-source src/cpdocs
 
-versions: [main]
+versions: [main, 0.3.7, 0.0.1]
 
 site:
   copyright: Copyright © cpdocs developers · Apache-2.0

{cpdocs-0.3.7 → cpdocs-0.3.9}/pyproject.toml

@@ -18,11 +18,9 @@ dependencies = [
   "markdown-it-py>=3",
   "Pygments>=2.17",
   "PyYAML>=6",
+  "keyso"
 ]
 
-[project.optional-dependencies]
-properdocs = ["properdocs>=1.6.7"]
-
 [project.urls]
 Source = "https://github.com/ambhora/cpdocs"
 

cpdocs-0.3.9/readme.md

@@ -0,0 +1,86 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# cpdocs
+
+cpdocs generates semantic, versioned API documentation for C, C++, CUDA, HIP, Fortran, Python and Rust projects.
+
+It asks the project's build system, through a small JSON contract, for the concrete feature sets to
+document. It builds each feature set independently, consumes the resulting manifest, extracts the API
+with Clang for C-family languages, source modules for Fortran, `ast` for Python or rustdoc JSON for
+Rust, and merges the results. Implementation files from the manifest are kept in the file hierarchy
+without becoming API entities.
+Feature-set availability and API language are tracked independently. The versions
+to publish are an explicit ordered list in `cpdocs.yml`.
+
+```console
+cpdocs build          # document the working tree into build/cpdocs/current
+cpdocs versions       # document the configured versions
+properdocs build      # project website with the versioned API mounted
+```
+
+## Language configurations
+
+The optional `languages` field in `docs/cpdocs.yml` is a [Keyso configuration
+space](https://ambhora.github.io/keyso/language/syntax/). cpdocs expands it using pykeyso,
+then runs `build.feature-sets` once per concrete configuration and `build.build` once per
+feature set discovered for that configuration. Both command templates receive dotted placeholders
+from the resulting nested dictionaries, such as `{{cxx.standard}}`, `{{c.standard}}`,
+`{{fortran.standard}}`, `{{python.version}}`, or `{{rust.edition}}`. The build system decides
+how to apply each value; cpdocs does not translate them into compiler flags.
+
+```yaml
+languages:
+  _product:
+    - cxx:
+        _nested:
+          standard: [17, 20, 23]
+    - python:
+        _nested:
+          version: ["3.11", "3.12"]
+
+build:
+  feature-sets: >-
+    cmake -S "{{source}}" -B "{{tmpdir}}"
+    -DCMAKE_CXX_STANDARD="{{cxx.standard}}"
+    -DPROJECT_FEATURE_SETS_OUTPUT="{{output-file}}"
+  build: >-
+    cmake -S "{{source}}" -B "{{tmpdir}}"
+    -DCMAKE_CXX_STANDARD="{{cxx.standard}}"
+    -DPROJECT_FEATURE_SET="{{feature-set}}"
+    -DPROJECT_CPDOCS_OUTPUT="{{output-file}}"
+    && cmake --build "{{tmpdir}}" --target project.cpdocs
+```
+
+Use `_set` for explicitly paired combinations rather than the `_product` Cartesian product:
+
+```yaml
+languages:
+  _set:
+    - cxx: {standard: 17}
+      python: {version: "3.11"}
+    - cxx: {standard: 23}
+      python: {version: "3.12"}
+```
+
+Each concrete configuration has its own work directory. The merged API records both the
+language configuration and feature set in symbol availability, including overload signatures.
+If `languages` is omitted, cpdocs performs the original single build configuration, and the
+existing `{{source}}`, `{{tmpdir}}`, `{{output-file}}`, `{{feature-set}}`, and `{{python}}`
+placeholders continue to work unchanged.
+
+The configuration lives in `docs/cpdocs.yml`, the API introduction in `docs/api/index.md` and the
+ProperDocs pages in `docs/web`. The documentation starts at `docs/web/index.md`; the `examples/`
+directory holds standalone projects that the test suite builds.
+
+## Development
+
+```console
+uv sync
+uv run pytest
+uv run ruff check && uv run ruff format --check
+```
+
+The C and C++ tests need `clang++`, `cmake` and `ninja`. Building the Rust example/site also needs
+the nightly toolchain pinned by `examples/rust-basic/rust-toolchain.toml`.

{cpdocs-0.3.7 → cpdocs-0.3.9}/src/cpdocs/__init__.py

@@ -4,4 +4,4 @@
 # --------------------------------------------------------------------------------------------------
 """Language-neutral semantic API documentation generator."""
 
-__version__ = "0.3.7"
+__version__ = "0.3.9"

{cpdocs-0.3.7 → cpdocs-0.3.9}/src/cpdocs/build.py

@@ -31,7 +31,11 @@ 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 .providers.contract import (
+    discover_feature_sets,
+    language_template_values,
+    resolve_manifest,
+)
 from .rendering.html import render_html_site
 from .versioning import SelectedRef, current_branch, select_refs
 
@@ -348,72 +352,114 @@ def build_graph(
     work: Path,
     version: str,
 ) -> ApiGraph:
-    """Discover every feature set, build each one independently, and merge the API graphs."""
-
-    feature_sets = discover_feature_sets(config.feature_sets, source=source, work=work)
+    """Build every allowed language configuration and its discovered feature sets."""
 
     per_feature_set: list[tuple[str, ApiGraph]] = []
     metadata: dict[str, object] = {}
     languages: set[str] = set()
     units: dict[tuple[str, str], None] = {}
     configuration_options: dict[str, list[dict[str, object]]] = {}
-
-    for feature_set in feature_sets.feature_sets:
-        manifest = resolve_manifest(config.build, feature_set, source=source, work=work)
-        if manifest.options:
-            configuration_options[feature_set.key] = [dict(option) for option in manifest.options]
-        languages.update(unit.language for unit in manifest.units if unit.language is not None)
-        for unit in manifest.units:
-            units[(unit.id, unit.language)] = None
-        feature_set_language_values = sorted(
-            {unit.language for unit in manifest.units if unit.language is not None}
+    all_feature_selections: list[dict[str, object]] = []
+    project: str | None = None
+    project_version = ""
+    generator = ""
+    multiple_languages = len(config.language_configurations) > 1
+
+    for index, configuration in enumerate(config.language_configurations, 1):
+        template_values = language_template_values(configuration)
+        # Preserve the existing work directory layout for projects with a single configuration.
+        language_work = (
+            work / "language-configurations" / f"language-{index:03d}"
+            if multiple_languages
+            else work
         )
-        if len(feature_set_language_values) == 1:
-            feature_set_language = feature_set_language_values[0]
-        elif feature_set_language_values:
-            feature_set_language = "mixed"
-        else:
-            feature_set_language = "none"
-        unit_graphs = []
-        for unit in manifest.units:
-            unit_graph = extract_unit(
-                unit,
-                project=feature_sets.project,
-                version=version,
-                project_root=source,
-                feature_set=feature_set.key,
-                work=work / "feature-sets" / feature_set.key,
-                config=config,
+        feature_sets = discover_feature_sets(
+            config.feature_sets,
+            source=source,
+            work=language_work,
+            template_values=template_values,
+        )
+        if project is None:
+            project = feature_sets.project
+            project_version = feature_sets.version
+            generator = feature_sets.generator
+        elif project != feature_sets.project:
+            raise RuntimeError(
+                f"build.feature-sets returned inconsistent projects: "
+                f"{project!r} and {feature_sets.project!r}"
             )
-            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 feature_set in feature_sets.feature_sets:
+            key = (
+                f"language-{index:03d}--{feature_set.key}"
+                if multiple_languages
+                else feature_set.key
             )
-            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)
-                existing.extend(path for path in generated_files if path not in existing)
-            unit_graphs.append(unit_graph)
-        graph = _combine(
-            unit_graphs,
-            project=feature_sets.project,
-            version=version,
-            language=feature_set_language,
-        )
-        graph.feature_sets[feature_set.key] = {
-            "features": list(feature_set.features),
-            "selection": feature_set.selection,
-        }
-        _merge_metadata(metadata, graph.metadata)
-        per_feature_set.append((feature_set.key, graph))
+            manifest = resolve_manifest(
+                config.build,
+                feature_set,
+                source=source,
+                work=language_work,
+                template_values=template_values,
+            )
+            if manifest.options:
+                configuration_options[key] = [dict(option) for option in manifest.options]
+            languages.update(unit.language for unit in manifest.units if unit.language is not None)
+            for unit in manifest.units:
+                units[(unit.id, unit.language)] = None
+            feature_set_language_values = sorted(
+                {unit.language for unit in manifest.units if unit.language is not None}
+            )
+            if len(feature_set_language_values) == 1:
+                feature_set_language = feature_set_language_values[0]
+            elif feature_set_language_values:
+                feature_set_language = "mixed"
+            else:
+                feature_set_language = "none"
+            unit_graphs = []
+            for unit in manifest.units:
+                unit_graph = extract_unit(
+                    unit,
+                    project=feature_sets.project,
+                    version=version,
+                    project_root=source,
+                    feature_set=key,
+                    work=language_work / "feature-sets" / feature_set.key,
+                    config=config,
+                )
+                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)
+                    existing.extend(path for path in generated_files if path not in existing)
+                unit_graphs.append(unit_graph)
+            graph = _combine(
+                unit_graphs,
+                project=feature_sets.project,
+                version=version,
+                language=feature_set_language,
+            )
+            graph.feature_sets[key] = {
+                "features": list(feature_set.features),
+                "selection": feature_set.selection,
+                "languages": configuration,
+            }
+            _merge_metadata(metadata, graph.metadata)
+            per_feature_set.append((key, graph))
+            all_feature_selections.append(feature_set.selection)
 
     language_values = sorted(languages)
     if len(language_values) == 1:
@@ -423,17 +469,18 @@ def build_graph(
     else:
         language = "none"
     merged = merge_graphs(
-        per_feature_set, project=feature_sets.project, version=version, language=language
+        per_feature_set, project=project or "", version=version, language=language
     )
-    metadata["feature_sets"] = [feature_set.selection for feature_set in feature_sets.feature_sets]
+    metadata["feature_sets"] = all_feature_selections
+    metadata["language_configurations"] = list(config.language_configurations)
     sorted_units = sorted(units, key=lambda value: (value[0], value[1] or ""))
     metadata["units"] = [
         {"id": unit_id, "language": unit_language} for unit_id, unit_language in sorted_units
     ]
     if configuration_options:
         metadata["configuration_options"] = configuration_options
-    metadata["generator"] = feature_sets.generator
-    metadata["project_version"] = feature_sets.version
+    metadata["generator"] = generator
+    metadata["project_version"] = project_version
     merged.metadata = metadata
 
     _apply_visibility(merged, config)

{cpdocs-0.3.7 → cpdocs-0.3.9}/src/cpdocs/config.py

@@ -28,6 +28,7 @@ class CpdocsConfig:
     project_root: Path
     feature_sets: str
     build: str
+    language_configurations: tuple[dict[str, Any], ...]
     versions: tuple[str, ...]
     index: Path | None
     copyright: str | None
@@ -86,6 +87,27 @@ def _command(value: object, name: str) -> str:
     return value.strip()
 
 
+def _language_configurations(raw: dict[str, Any]) -> tuple[dict[str, Any], ...]:
+    """Expand the optional Keyso language space, preserving the original default build."""
+
+    if "languages" not in raw:
+        return ({},)
+    expression = _mapping(raw["languages"], "languages")
+    try:
+        import keyso
+    except ImportError as error:
+        raise RuntimeError("cpdocs.yml: languages requires the keyso package") from error
+    try:
+        configurations = keyso.expand(expression)
+    except Exception as error:
+        raise RuntimeError(f"cpdocs.yml: invalid languages Keyso space: {error}") from error
+    if not configurations:
+        raise RuntimeError("cpdocs.yml: languages must expand to at least one configuration")
+    if not all(isinstance(configuration, dict) for configuration in configurations):
+        raise RuntimeError("cpdocs.yml: languages must expand to dictionaries")
+    return tuple(configurations)
+
+
 def load_config(path: Path | str = DEFAULT_CONFIG) -> CpdocsConfig:
     config_file = Path(path).expanduser().resolve()
     if not config_file.is_file():
@@ -97,7 +119,7 @@ def load_config(path: Path | str = DEFAULT_CONFIG) -> CpdocsConfig:
         raise RuntimeError(
             f"cpdocs.yml: contract must be {CONTRACT_VERSION}, found {raw.get('contract')!r}"
         )
-    known = {"contract", "build", "versions", "site", "api", "checks"}
+    known = {"contract", "build", "languages", "versions", "site", "api", "checks"}
     unknown = sorted(set(raw) - known)
     if unknown:
         raise RuntimeError(f"cpdocs.yml: unknown top-level keys: {', '.join(unknown)}")
@@ -123,6 +145,7 @@ def load_config(path: Path | str = DEFAULT_CONFIG) -> CpdocsConfig:
         project_root=root,
         feature_sets=_command(build.get("feature-sets"), "build.feature-sets"),
         build=_command(build.get("build"), "build.build"),
+        language_configurations=_language_configurations(raw),
         versions=_versions(raw.get("versions")),
         index=index if index.is_file() else None,
         copyright=str(copyright_value) if copyright_value is not None else None,

{cpdocs-0.3.7 → cpdocs-0.3.9}/src/cpdocs/providers/contract.py

@@ -22,7 +22,31 @@ from ..contract import (
     write_feature_set,
 )
 
-_PLACEHOLDER = re.compile(r"\{\{([a-z][a-z0-9-]*)\}\}")
+_PLACEHOLDER = re.compile(r"\{\{\s*([a-z][a-z0-9_.-]*)\s*\}\}")
+
+
+def language_template_values(configuration: dict[str, object]) -> dict[str, str]:
+    """Flatten concrete Keyso values into dotted command-template placeholders."""
+
+    result: dict[str, str] = {}
+
+    def visit(path: str, value: object) -> None:
+        if isinstance(value, dict):
+            for key, child in value.items():
+                if not isinstance(key, str) or not re.fullmatch(r"[a-z][a-z0-9_-]*", key):
+                    raise RuntimeError(f"cpdocs.yml: invalid language property {key!r}")
+                visit(f"{path}.{key}" if path else key, child)
+        elif isinstance(value, (str, int, float, bool)) and not isinstance(value, complex):
+            if not path:
+                raise RuntimeError("cpdocs.yml: language configuration needs a property name")
+            if path in {"source", "tmpdir", "output-file", "feature-set", "python"}:
+                raise RuntimeError(f"cpdocs.yml: language property {path!r} is reserved")
+            result[path] = str(value).lower() if isinstance(value, bool) else str(value)
+        else:
+            raise RuntimeError(f"cpdocs.yml: language property {path!r} must be a scalar value")
+
+    visit("", configuration)
+    return result
 
 
 def _expand(command: str, values: dict[str, str], *, allowed: set[str], name: str) -> str:
@@ -71,7 +95,9 @@ def _run_command(
         )
 
 
-def discover_feature_sets(command: str, *, source: Path, work: Path) -> FeatureSets:
+def discover_feature_sets(
+    command: str, *, source: Path, work: Path, template_values: dict[str, str] | None = None
+) -> FeatureSets:
     """Run ``build.feature-sets`` and read ``feature-sets.json``."""
 
     directory = work / "feature-sets"
@@ -87,8 +113,9 @@ def discover_feature_sets(command: str, *, source: Path, work: Path) -> FeatureS
             "tmpdir": str(tmpdir.resolve()),
             "output-file": str(output.resolve()),
             "python": sys.executable,
+            **(template_values or {}),
         },
-        allowed={"source", "tmpdir", "output-file", "python"},
+        allowed={"source", "tmpdir", "output-file", "python"} | set(template_values or {}),
         name="feature-sets",
         log=directory / "log.txt",
     )
@@ -96,7 +123,12 @@ def discover_feature_sets(command: str, *, source: Path, work: Path) -> FeatureS
 
 
 def resolve_manifest(
-    command: str, feature_set: FeatureSetDeclaration, *, source: Path, work: Path
+    command: str,
+    feature_set: FeatureSetDeclaration,
+    *,
+    source: Path,
+    work: Path,
+    template_values: dict[str, str] | None = None,
 ) -> Manifest:
     """Run ``build.build`` for one feature set and read ``manifest.json``."""
 
@@ -116,8 +148,10 @@ def resolve_manifest(
             "feature-set": str(feature_set_file.resolve()),
             "output-file": str(output.resolve()),
             "python": sys.executable,
+            **(template_values or {}),
         },
-        allowed={"source", "tmpdir", "feature-set", "output-file", "python"},
+        allowed={"source", "tmpdir", "feature-set", "output-file", "python"}
+        | set(template_values or {}),
         name="build",
         log=directory / "log.txt",
     )