mafw.devtools.documentation.versions

Version management helpers for MAFw versioned documentation.

This module provides functions for writing versions.json, creating redirect pages, mirroring version directories, pruning old versions, and generating landing pages.

Functions

ensure_versions_json_exists(outdir)	Ensure versions.json exists in outdir.
format_size(bytes_size)	Format bytes to human-readable size.
get_directory_size(path)	Calculate total size of a directory in bytes.
mirror_version(outdir, src_tag, target_tag)	Mirror a version directory from one tag to another.
prune_old_versions(outdir[, max_size_mb, ...])	Remove oldest version directories until total size is below threshold.
regenerate_versions_json_after_pruning(...)	Regenerate versions.json after pruning, excluding removed versions.
write_legacy_redirect_page(outdir)	Create a legacy redirect page at the root of the output directory.
write_redirect_page(outdir, name, target_tag)	Create a redirect page for a version alias.
write_redirects_file(outdir)	Create a _redirects file for GitLab Pages.
write_root_landing_page(build_root[, ...])	Create a landing page for the project root with links to documentation and coverage.
write_versions_json(outdir, versions)	Write versions information to a JSON file.

mafw.devtools.documentation.versions.ensure_versions_json_exists(outdir: Path) → bool

Ensure versions.json exists in outdir. If not, try to copy from another version.

Parameters:

outdir (Path) – Output directory that should contain versions.json

Returns:

True if versions.json exists or was successfully copied

Return type:

bool

mafw.devtools.documentation.versions.format_size(bytes_size: float) → str

Format bytes to human-readable size.

Parameters:

bytes_size (int) – Size in bytes

Returns:

Formatted size string

Return type:

str

mafw.devtools.documentation.versions.get_directory_size(path: Path) → int

Calculate total size of a directory in bytes.

Parameters:

path (Path) – Directory path

Returns:

Total size in bytes

Return type:

int

mafw.devtools.documentation.versions.mirror_version(outdir: Path, src_tag: str, target_tag: str, use_symlink: bool = True) → None

Mirror a version directory from one tag to another. Can use symlinks for efficiency or copy for compatibility.

Parameters:

• outdir (Path) – Output directory containing version directories

• src_tag (str) – Source tag directory name

• target_tag (str) – Target tag directory name

• use_symlink (bool) – Whether to use symlink instead of copying, defaults to True

mafw.devtools.documentation.versions.prune_old_versions(outdir: Path, max_size_mb: int = 100, dry_run: bool = False) → tuple[list[str], int]

Remove oldest version directories until total size is below threshold. Always keeps ‘stable’, ‘latest’, and ‘dev’ (if present).

Parameters:

• outdir (Path) – Output directory containing version directories

• max_size_mb (int) – Maximum size in megabytes

• dry_run (bool) – If True, only report what would be deleted

Returns:

Tuple of (list of removed versions, final size in bytes)

Return type:

tuple[list[str], int]

mafw.devtools.documentation.versions.regenerate_versions_json_after_pruning(outdir: Path, removed_versions: list[str]) → None

Regenerate versions.json after pruning, excluding removed versions.

Parameters:

• outdir (Path) – Output directory containing version directories

• removed_versions (list[str]) – List of version names that were removed

mafw.devtools.documentation.versions.write_legacy_redirect_page(outdir: Path) → None

Create a legacy redirect page at the root of the output directory.

Parameters:

outdir (Path) – Output directory for the redirect page

mafw.devtools.documentation.versions.write_redirect_page(outdir: Path, name: str, target_tag: str) → None

Create a redirect page for a version alias.

Parameters:

• outdir (Path) – Output directory for the redirect page

• name (str) – Name of the redirect alias (e.g., ‘stable’, ‘dev’)

• target_tag (str) – Tag that the redirect should point to

mafw.devtools.documentation.versions.write_redirects_file(outdir: Path) → None

Create a _redirects file for GitLab Pages.

Parameters:

outdir (Path) – Output directory for the redirects file

mafw.devtools.documentation.versions.write_root_landing_page(build_root: Path, project_name: str = 'MAFw') → None

Create a landing page for the project root with links to documentation and coverage.

Parameters:

• build_root (Path) – Root build directory (should contain ‘doc’ subdirectory)

• project_name (str) – Project name for the page title

mafw.devtools.documentation.versions.write_versions_json(outdir: Path, versions: list[dict[str, str]]) → None

Write versions information to a JSON file.

Parameters:

• outdir (Path) – Output directory for the JSON file

• versions (list[dict[str, str]]) – List of version information dictionaries