stamp_docs_revision Namespace Reference

Functions
str	git_output (*str args)
	Return trimmed output from one Git command.
dict	resolve_release_identity (bool dirty)
	Resolve the PICurv release identity the same way the conductor does.
argparse.Namespace	parse_args ()
	Parse generated-documentation stamping arguments.
int	main ()
	Write revision metadata and load it on every generated HTML page.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]

Detailed Description

Stamp generated Doxygen HTML with the Git revision it documents.

Function Documentation

git_output()

str stamp_docs_revision.git_output

(

*str

args

)

Return trimmed output from one Git command.

Parameters

[in]

args

Arguments passed after git.

Returns

Decoded, trimmed Git stdout.

Definition at line 15 of file stamp_docs_revision.py.

def git_output(*args: str) -> str:
    """!
    @brief Return trimmed output from one Git command.
    @param[in] args Arguments passed after `git`.
    @return Decoded, trimmed Git stdout.
    """
 
    return subprocess.check_output(["git", *args], cwd=REPO_ROOT, text=True).strip()
 
 

Here is the caller graph for this function:

resolve_release_identity()

dict stamp_docs_revision.resolve_release_identity

(

bool

dirty

)

Resolve the PICurv release identity the same way the conductor does.

Mirrors _source_build_identity() in picurv_cli/core.py using only Git and the VERSION file, so the docs build stays free of a picurv_cli import (and its PETSc-adjacent dependency chain) while still reporting the same release_version / build_id a user sees from picurv version.

Parameters

[in]

dirty

Whether the working tree carries uncommitted tracked changes.

Returns

Mapping with release_version, build_id, and released.

Definition at line 25 of file stamp_docs_revision.py.

def resolve_release_identity(dirty: bool) -> dict:
    """!
    @brief Resolve the PICurv release identity the same way the conductor does.
 
    @details Mirrors `_source_build_identity()` in `picurv_cli/core.py` using only Git
             and the `VERSION` file, so the docs build stays free of a `picurv_cli`
             import (and its PETSc-adjacent dependency chain) while still reporting the
             same `release_version` / `build_id` a user sees from `picurv version`.
    @param[in] dirty Whether the working tree carries uncommitted tracked changes.
    @return Mapping with `release_version`, `build_id`, and `released`.
    """
 
    release_version = (REPO_ROOT / "VERSION").read_text(encoding="utf-8").strip()
    short_sha = git_output("rev-parse", "--short=12", "HEAD")
    dev_distance = None
    describe = subprocess.run(
        ["git", "describe", "--tags", "--match", f"v{release_version}", "--long"],
        cwd=REPO_ROOT, text=True, capture_output=True, check=False,
    )
    if describe.returncode == 0:
        parts = describe.stdout.strip().rsplit("-", 2)
        if len(parts) == 3 and parts[1].isdigit():
            dev_distance = int(parts[1])
    else:
        dev_distance = int(git_output("rev-list", "--count", "HEAD"))
    released = dev_distance == 0 and not dirty
    suffix = "" if dev_distance in (0, None) else f".dev{dev_distance}"
    build_id = f"{release_version}{suffix}+g{short_sha}" + (".dirty" if dirty else "")
    return {"release_version": release_version, "build_id": build_id, "released": released}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

parse_args()

argparse.Namespace stamp_docs_revision.parse_args

(

)

Parse generated-documentation stamping arguments.

Returns

Parsed command-line namespace.

Definition at line 56 of file stamp_docs_revision.py.

def parse_args() -> argparse.Namespace:
    """!
    @brief Parse generated-documentation stamping arguments.
    @return Parsed command-line namespace.
    """
 
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--html-dir", type=Path, required=True, help="generated Doxygen HTML directory")
    return parser.parse_args()
 
 

Here is the caller graph for this function:

main()

int stamp_docs_revision.main

(

)

Write revision metadata and load it on every generated HTML page.

Returns

Process status code.

Definition at line 67 of file stamp_docs_revision.py.

def main() -> int:
    """!
    @brief Write revision metadata and load it on every generated HTML page.
    @return Process status code.
    """
 
    args = parse_args()
    html_dir = args.html_dir.resolve()
    if not html_dir.is_dir():
        raise SystemExit(f"HTML directory does not exist: {html_dir}")
    sha = git_output("rev-parse", "HEAD")
    remote = git_output("remote", "get-url", "origin")
    if remote.startswith("git@github.com:"):
        remote = "https://github.com/" + remote[len("git@github.com:"):]
    if remote.endswith(".git"):
        remote = remote[:-4]
    clean = not bool(git_output("status", "--porcelain"))
    revision = {
        "sha": sha,
        "short_sha": sha[:12],
        "commit_url": f"{remote}/commit/{sha}",
        "clean": clean,
        **resolve_release_identity(dirty=not clean),
    }
    (html_dir / "picurv-docs-revision.js").write_text(
        "window.PICURV_DOCS_REVISION = " + json.dumps(revision, sort_keys=True) + ";\n",
        encoding="utf-8",
    )
    for page in html_dir.rglob("*.html"):
        relative = page.relative_to(html_dir)
        script_path = "../picurv-docs-revision.js" if relative.parts[0] == "search" else "picurv-docs-revision.js"
        content = page.read_text(encoding="utf-8")
        if "picurv-docs-revision.js" not in content:
            content = content.replace("</head>", f'<script src="{script_path}"></script>\n</head>')
            page.write_text(content, encoding="utf-8")
    print(f"Stamped generated documentation as PICurv {revision['build_id']} (commit {sha}).")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

REPO_ROOT

stamp_docs_revision.REPO_ROOT = Path(__file__).resolve().parents[2]

Definition at line 12 of file stamp_docs_revision.py.