Functions
str	identifier_slug (str value)
	Build a safe Doxygen/file identifier from a free-form title.

str	slug (str value)
	Anchor slug for a selector value.

int	next_page_number ()
	Lowest unused page number in docs/pages.

str	capability_entry (str family_id, str value)
	Render a Tier-2 capability entry carrying every required contract part.

str	alias_stub (str family_id, str value, str canonical)
	Render a deprecated-alias stub, which owes three parts rather than eight.

str	suggested_filename (str title, int number)
	Filename for a scaffolded page, using the same sanitized identifier as the page ID.

str	page (str kind, str title, int number)
	Render a page skeleton shaped to its document type's contract.

str	subsystem_record (str identifier, str title)
	Render the machine-readable lifecycle record a `planned` subsystem owes.

str	subsystem_charter (str identifier, str title)
	Render a subsystem charter at the `planned` lifecycle stage.

int	main ()
	Emit a documentation skeleton for the requested kind.

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

str	PAGES_DIR = REPO_ROOT / "docs" / "pages"

str	FAMILIES_PATH = REPO_ROOT / "tests" / "tooling" / "capability_families.json"

dict	PAGE_TYPES

str	INCOMPLETE_MARKER = "@par SCAFFOLD-INCOMPLETE"

tuple	INCOMPLETE_NOTE

dict	PAGE_SECTIONS

Detailed Description

Generate documentation skeletons that satisfy the repository's own contracts.

Function Documentation

◆ identifier_slug()

str scaffold_documentation.identifier_slug ( str value )

Build a safe Doxygen/file identifier from a free-form title.

Titles may contain characters that are illegal in a Doxygen identifier or that would imply a nested path in a filename. The display title is kept intact; only the identifier is sanitized.

Parameters

[in] value Free-form title.

Returns: Safe identifier.

Exceptions

SystemExit when nothing usable remains.

Definition at line 39 of file scaffold_documentation.py.

def identifier_slug(value: str) -> str:
    """!
    @brief Build a safe Doxygen/file identifier from a free-form title.
 
    @details Titles may contain characters that are illegal in a Doxygen identifier or
             that would imply a nested path in a filename. The display title is kept
             intact; only the identifier is sanitized.
    @param[in] value Free-form title.
    @return Safe identifier.
    @throws SystemExit when nothing usable remains.
    """
    cleaned = re.sub(r"[^A-Za-z0-9]+", "_", value).strip("_")
    cleaned = re.sub(r"_{2,}", "_", cleaned)
    if not cleaned:
        raise SystemExit(
            f"Title {value!r} contains no characters usable in an identifier; "
            f"choose a title with letters or digits."
        )
    if cleaned[0].isdigit():
        cleaned = f"p_{cleaned}"
    return cleaned
 
 

Here is the caller graph for this function:

◆ slug()

str scaffold_documentation.slug ( str value )

Anchor slug for a selector value.

Parameters

[in] value Public selector value.

Returns: Lowercase underscore slug.

Definition at line 62 of file scaffold_documentation.py.

def slug(value: str) -> str:
    """!
    @brief Anchor slug for a selector value.
    @param[in] value Public selector value.
    @return Lowercase underscore slug.
    """
    return re.sub(r"[^a-z0-9]+", "_", value.lower()).strip("_")
 
 

Here is the caller graph for this function:

◆ next_page_number()

int scaffold_documentation.next_page_number ( )

Lowest unused page number in docs/pages.

Returns: Next available page number.

Definition at line 71 of file scaffold_documentation.py.

def next_page_number() -> int:
    """!
    @brief Lowest unused page number in docs/pages.
    @return Next available page number.
    """
    used = {
        int(match.group(1))
        for path in PAGES_DIR.glob("*.md")
        if (match := re.match(r"(\d+)_", path.name))
    }
    return max(used) + 1 if used else 1
 
 

Here is the caller graph for this function:

◆ capability_entry()

str scaffold_documentation.capability_entry	(	str	family_id,
		str	value
	)

Render a Tier-2 capability entry carrying every required contract part.

Parameters

[in]	family_id	Capability family identifier.
[in]	value	Public selector value.

Returns: Markdown text for the entry.

Definition at line 84 of file scaffold_documentation.py.

def capability_entry(family_id: str, value: str) -> str:
    """!
    @brief Render a Tier-2 capability entry carrying every required contract part.
    @param[in] family_id Capability family identifier.
    @param[in] value Public selector value.
    @return Markdown text for the entry.
    """
    families = {f["id"]: f for f in json.loads(FAMILIES_PATH.read_text(encoding="utf-8"))["families"]}
    family = families.get(family_id)
    if family is None:
        raise SystemExit(
            f"Unknown family '{family_id}'. Known: {', '.join(sorted(families))}"
        )
    anchor = family["entry_anchor_prefix"] + slug(value)
    return f"""@subsection {anchor}_sub {value}
 
@anchor {anchor}
 
{INCOMPLETE_NOTE}
 
**Identity.** `{family['selector']}` = `{value}` -> TODO: generated flag -> TODO: C enum
-> @ref TODO_implementing_function.
 
**What it does.** TODO: the behavior, in a short paragraph.
 
**When to choose it.** TODO: compare explicitly against its siblings in this family.
An entry that does not compare is a description, not guidance.
 
**Parameters it owns.** TODO: options exclusive to this value, required and optional
separated. Options shared across the family belong on the family page.
 
**Interactions.** TODO: what it requires, conflicts with, or implies, including
anything enforced by validation.
 
**Diagnostics.** TODO: what it logs, and how a reader tells it is working. Name the
failure signature, not only the success one.
 
**Evidence.** TODO: facets with sources, or state "Implemented only." Record the same
sources in `value_metadata["{value}"]["evidence"]` in
`tests/tooling/capability_families.json` - the audit checks they match.
 
**Limitations.** TODO: what it cannot do.
"""
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ alias_stub()

str scaffold_documentation.alias_stub	(	str	family_id,
		str	value,
		str	canonical
	)

Render a deprecated-alias stub, which owes three parts rather than eight.

Parameters

[in]	family_id	Capability family identifier.
[in]	value	Deprecated selector value.
[in]	canonical	Canonical value it resolves to.

Returns: Markdown text for the stub.

Definition at line 129 of file scaffold_documentation.py.

def alias_stub(family_id: str, value: str, canonical: str) -> str:
    """!
    @brief Render a deprecated-alias stub, which owes three parts rather than eight.
    @param[in] family_id Capability family identifier.
    @param[in] value Deprecated selector value.
    @param[in] canonical Canonical value it resolves to.
    @return Markdown text for the stub.
    """
    families = {f["id"]: f for f in json.loads(FAMILIES_PATH.read_text(encoding="utf-8"))["families"]}
    family = families.get(family_id)
    if family is None:
        raise SystemExit(f"Unknown family '{family_id}'. Known: {', '.join(sorted(families))}")
    known = set(family.get("value_metadata", {}))
    if known and canonical not in known:
        raise SystemExit(
            f"Canonical target '{canonical}' is not a declared value of '{family_id}'. "
            f"Known: {', '.join(sorted(known))}"
        )
    anchor = family["entry_anchor_prefix"] + slug(value)
    return f"""@subsection {anchor}_sub {value} (deprecated)
 
@anchor {anchor}
 
{INCOMPLETE_NOTE}
 
**Identity.** `{value}` - a **deprecated alias** that normalizes to `{canonical}`.
 
**Status.** Deprecated. TODO: why it still parses.
 
**Migration.** TODO: the exact edits to move to `{canonical}`.
"""
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ suggested_filename()

str scaffold_documentation.suggested_filename	(	str	title,
		int	number
	)

Filename for a scaffolded page, using the same sanitized identifier as the page ID.

Parameters

[in]	title	Free-form page title.
[in]	number	Page number.

Returns: Safe filename.

Definition at line 195 of file scaffold_documentation.py.

def suggested_filename(title: str, number: int) -> str:
    """!
    @brief Filename for a scaffolded page, using the same sanitized identifier as the page ID.
    @param[in] title Free-form page title.
    @param[in] number Page number.
    @return Safe filename.
    """
    return f"{number:02d}_{identifier_slug(title)}.md"
 
 

◆ page()

str scaffold_documentation.page	(	str	kind,
		str	title,
		int	number
	)

Render a page skeleton shaped to its document type's contract.

Each type gets the sections it actually owes, not a generic outline. A tutorial that does not state its outcome, or a reference that does not declare its scope, is not the type it claims to be.

Parameters

[in]	kind	Page type key.
[in]	title	Human-readable page title.
[in]	number	Page number.

Returns: Markdown text for the page.

Definition at line 205 of file scaffold_documentation.py.

def page(kind: str, title: str, number: int) -> str:
    """!
    @brief Render a page skeleton shaped to its document type's contract.
 
    @details Each type gets the sections it actually owes, not a generic outline. A
             tutorial that does not state its outcome, or a reference that does not
             declare its scope, is not the type it claims to be.
    @param[in] kind Page type key.
    @param[in] title Human-readable page title.
    @param[in] number Page number.
    @return Markdown text for the page.
    """
    safe = identifier_slug(title)
    identifier = f"{number:02d}_{safe}"
    owes = {
        "tutorial": "a working outcome: every command runs as written, from a stated starting state",
        "how-to": "a completed task, assuming the reader can already run PICurv",
        "reference": "accuracy and completeness within its declared scope",
        "explanation": "understanding: why it is like this, and what the alternatives were",
        "hub": "complete and current routing, and nothing else",
    }[kind]
 
    body = [
        f"@page {identifier} {title}",
        "",
        f"@anchor _{safe}",
        "",
        f"@pagemeta{{{PAGE_TYPES[kind]}, TODO audience, TODO status}}",
        "",
        INCOMPLETE_NOTE,
        "",
        "TODO: one paragraph saying what this page is for.",
        "",
        f"This page owes the reader {owes}. See **@subpage 63_Page_Type_Contract** for what a",
        f"{PAGE_TYPES[kind]} must refuse to do.",
        "",
        "@tableofcontents",
        "",
    ]
    for index, (heading, guidance) in enumerate(PAGE_SECTIONS[kind], start=1):
        section = identifier_slug(heading).lower()
        body += [f"@section p{number}_{section}_sec {index}. {heading}", "", guidance, ""]
    last = len(PAGE_SECTIONS[kind]) + 1
    body += [
        f"@section p{number}_related_sec {last}. Related Documentation",
        "",
        "- **@subpage 47_Documentation_Catalog**",
        "",
    ]
    return "\n".join(body)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ subsystem_record()

str scaffold_documentation.subsystem_record	(	str	identifier,
		str	title
	)

Render the machine-readable lifecycle record a planned subsystem owes.

The charter is prose; this is the record make audit-subsystems reads. A planned subsystem owes only four obligations, so the stub is short by design - the gate grows with the status, not with the scaffold.

Parameters

[in]	identifier	Subsystem id.
[in]	title	Human-readable subsystem name.

Returns: JSON text to paste into tests/tooling/subsystem_records.json.

Definition at line 257 of file scaffold_documentation.py.

def subsystem_record(identifier: str, title: str) -> str:
    """!
    @brief Render the machine-readable lifecycle record a `planned` subsystem owes.
 
    @details The charter is prose; this is the record `make audit-subsystems` reads.
             A planned subsystem owes only four obligations, so the stub is short by
             design - the gate grows with the status, not with the scaffold.
    @param[in] identifier Subsystem id.
    @param[in] title Human-readable subsystem name.
    @return JSON text to paste into tests/tooling/subsystem_records.json.
    """
    record = {
        "id": identifier,
        "title": title,
        "status": "planned",
        "visibility": "public",
        "previous_status": None,
        "capability_families": [],
        "obligations": {
            "purpose": {"page": "TODO_page_id", "anchor": "TODO_anchor"},
            "intended_scope": {"page": "TODO_page_id", "anchor": "TODO_anchor"},
            "design_owner": {"value": "TODO: name"},
            "not_implemented_status": {"page": "TODO_page_id", "anchor": "TODO_anchor"},
        },
        "concerns": {},
    }
    return json.dumps(record, indent=2)
 
 

Here is the caller graph for this function:

◆ subsystem_charter()

str scaffold_documentation.subsystem_charter	(	str	identifier,
		str	title
	)

Render a subsystem charter at the planned lifecycle stage.

Requirements grow with the status a subsystem claims, so this scaffold asks only what planned owes. The later stages are listed so the author can see what each promotion will require.

Parameters

[in]	identifier	Subsystem identifier.
[in]	title	Human-readable subsystem name.

Returns: Markdown text for the charter.

Definition at line 286 of file scaffold_documentation.py.

def subsystem_charter(identifier: str, title: str) -> str:
    """!
    @brief Render a subsystem charter at the `planned` lifecycle stage.
 
    @details Requirements grow with the status a subsystem claims, so this scaffold
             asks only what `planned` owes. The later stages are listed so the author
             can see what each promotion will require.
    @param[in] identifier Subsystem identifier.
    @param[in] title Human-readable subsystem name.
    @return Markdown text for the charter.
    """
    return f"""# Subsystem charter: {title}
 
{INCOMPLETE_MARKER} - replace every TODO, then delete this line.
 
Identifier: `{identifier}`
Lifecycle status: **planned**
 
## Purpose
 
TODO: what problem this solves, and for whom.
 
## Intended scope
 
TODO: what it will cover.
 
## Explicitly out of scope
 
TODO: what it will not cover. This is the most useful section to write early.
 
## Design owner
 
TODO: name.
 
## Not implemented
 
This subsystem is `planned`. Nothing here describes working behavior, and it must not
appear in user-facing reference until it reaches `public experimental`.
 
## Concern modules
 
Declare which apply, per **64_Documentation_Extension_Framework**. A concern may be
marked not applicable **with a stated reason**; an empty heading is not an answer.
 
- [ ] Numerical method
- [ ] User selector
- [ ] Units and nondimensionalization
- [ ] Artifact topology and storage lifecycle
- [ ] Persistent/restart state
- [ ] Determinism and reproducibility
- [ ] MPI/distributed execution
- [ ] External service
- [ ] Security/credentials
- [ ] Generated artifact
- [ ] File format
- [ ] Concurrency, permissions, destructive scope
- [ ] Backward compatibility
- [ ] Scientific verification and validation
 
## What each promotion will require
 
| To reach | Add |
|---|---|
| `internal` | Scope boundary, architecture boundary, dependencies, developer entry points |
| `public experimental` | Configuration, selection guidance, observability, limitations, safe-use boundaries |
| `supported` | Evidence, lifecycle and restart behavior, operations, troubleshooting, examples, complete reference |
"""
 
 

Here is the caller graph for this function:

◆ main()

int scaffold_documentation.main ( )

Emit a documentation skeleton for the requested kind.

Returns: Process status code.

Definition at line 355 of file scaffold_documentation.py.

def main() -> int:
    """!
    @brief Emit a documentation skeleton for the requested kind.
    @return Process status code.
    """
    parser = argparse.ArgumentParser(
        description="Generate documentation skeletons that satisfy the repository's contracts.",
        epilog=(
            "Examples:\n"
            "  scaffold_documentation.py capability --family boundary.handler --value slip_wall\n"
            "  scaffold_documentation.py alias --family momentum.solver --value 'Old Name' "
            "--canonical 'New Name'\n"
            "  scaffold_documentation.py page --type how-to --title 'Running On A Cluster'\n"
            "  scaffold_documentation.py subsystem --id ibm --title 'Immersed Boundaries'\n"
        ),
        formatter_class=argparse.RawTextHelpFormatter,
    )
    sub = parser.add_subparsers(dest="kind", required=True)
 
    p_cap = sub.add_parser("capability", help="A Tier-2 entry for a new selector value.")
    p_cap.add_argument("--family", required=True)
    p_cap.add_argument("--value", required=True)
 
    p_alias = sub.add_parser("alias", help="A deprecated-alias stub.")
    p_alias.add_argument("--family", required=True)
    p_alias.add_argument("--value", required=True)
    p_alias.add_argument("--canonical", required=True)
 
    p_page = sub.add_parser("page", help="A new documentation page of a declared type.")
    p_page.add_argument("--type", required=True, choices=sorted(PAGE_TYPES))
    p_page.add_argument("--title", required=True)
 
    p_sub = sub.add_parser("subsystem", help="A subsystem charter at the planned stage.")
    p_sub.add_argument("--id", required=True)
    p_sub.add_argument("--title", required=True)
 
    args = parser.parse_args()
 
    if args.kind == "capability":
        print(capability_entry(args.family, args.value))
        print("# Next: paste into the family page, then run 'make audit-capability'.", file=sys.stderr)
    elif args.kind == "alias":
        print(alias_stub(args.family, args.value, args.canonical))
        print("# Next: declare alias_of in capability_families.json.", file=sys.stderr)
    elif args.kind == "page":
        number = next_page_number()
        print(page(args.type, args.title, number))
        print(
            f"# Next: save as docs/pages/{suggested_filename(args.title, number)}, "
            f"then adopt it with @subpage from a hub page or it will be reported as orphaned.",
            file=sys.stderr,
        )
    else:
        print(subsystem_charter(args.id, args.title))
        print("\n<!-- Paste into the \"subsystems\" list of "
              "tests/tooling/subsystem_records.json:\n")
        print(subsystem_record(args.id, args.title))
        print("-->")
        print("# Next: add the record above to tests/tooling/subsystem_records.json and run\n"
              "#       make audit-subsystems. Record it in the contract registry too if it\n"
              "#       introduces invariants.", file=sys.stderr)
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ REPO_ROOT

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

Definition at line 13 of file scaffold_documentation.py.

◆ PAGES_DIR

str scaffold_documentation.PAGES_DIR = REPO_ROOT / "docs" / "pages"

Definition at line 14 of file scaffold_documentation.py.

◆ FAMILIES_PATH

str scaffold_documentation.FAMILIES_PATH = REPO_ROOT / "tests" / "tooling" / "capability_families.json"

Definition at line 15 of file scaffold_documentation.py.

◆ PAGE_TYPES

dict scaffold_documentation.PAGE_TYPES

Initial value:

=  {
    "tutorial": "Tutorial",
    "how-to": "How-to",
    "reference": "Reference",
    "explanation": "Explanation",
    "hub": "Hub",
}

Definition at line 17 of file scaffold_documentation.py.

◆ INCOMPLETE_MARKER

str scaffold_documentation.INCOMPLETE_MARKER = "@par SCAFFOLD-INCOMPLETE"

Definition at line 30 of file scaffold_documentation.py.

◆ INCOMPLETE_NOTE

tuple scaffold_documentation.INCOMPLETE_NOTE

Initial value:

=  (
    f"{INCOMPLETE_MARKER}\n"
    "This was generated from a scaffold and is not finished. Replace every TODO, then\n"
    "delete this block. Publication gates reject the marker, so an untouched scaffold\n"
    "cannot ship."
)

Definition at line 31 of file scaffold_documentation.py.

◆ PAGE_SECTIONS

dict scaffold_documentation.PAGE_SECTIONS

Definition at line 162 of file scaffold_documentation.py.

Functions

Variables

Detailed Description

Function Documentation

◆ identifier_slug()

◆ slug()

◆ next_page_number()

◆ capability_entry()

◆ alias_stub()

◆ suggested_filename()

◆ page()

◆ subsystem_record()

◆ subsystem_charter()

◆ main()

Variable Documentation

◆ REPO_ROOT

◆ PAGES_DIR

◆ FAMILIES_PATH

◆ PAGE_TYPES

◆ INCOMPLETE_MARKER

◆ INCOMPLETE_NOTE

◆ PAGE_SECTIONS