Skip to content

docs: correct guide examples and enforce documentation checks - #1492

Merged
Brad-Edwards merged 12 commits into
devfrom
guides-imports-rename
Nov 3, 2026
Merged

Brad-Edwards merged 12 commits into
devfrom
guides-imports-rename

Conversation

@doublewhy

@doublewhy doublewhy commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Correct the public CLI and Python guides, make the rename and removal examples succeed, and close the documentation-check gaps found during review.

Changes

  • Document the current text-parser and semantic CLI limits for SDL imports.
  • Use a standalone rename example and state the paired infrastructure-key limit.
  • Remove an existing content declaration with explicit loss permission and show the result.
  • Document the registered runtime CLI group, including members hidden by module __all__.
  • Execute the Python and offline CLI guide blocks in the existing docs lane. Negative mutations restore the broken rename/removal targets and remove loss permission.
  • Check the guide sample inventory and report the host-dependent control-plane fragment as an explicit skip.
  • Run Vale on public Markdown and reStructuredText with the frozen project environment supplying rst2html. Correct the exposed reference prose and headings.
  • Refresh immutable runtime-mapping evidence for the updated source tree; retain previous captures.

Requirement UIDs

  • None. Documentation and verification maintenance; no product behavior or requirement completion is claimed.

Related Issues

No issue: correct public guides and repair their verification without changing package behavior.

The documented product limits are tracked in #1548 and #1550. Documentation-example execution and reStructuredText coverage were reported in #1554 and #1562. This PR does not claim delivery of unrelated issue acceptance criteria or close those issues.

ADR Impact

  • No ADR required. Reuses the existing documentation lane and module ownership.
  • Design: docs/decisions/pr-1492-guide-checks.md.

Test Plan

  • Static Ruff formatting/lint and whitespace checks pass.
  • Current-head CI passes, including the docs lane, guide mutations, and runtime-mapping drift checks.
  • Full test, integration, fuzz, and completion verification runs only in CI.
  • Final head be4466978: all eight test shards, integration, policy, documentation, proof/model checks, coverage, and the required CI gate passed.
  • PR SonarCloud quality gate: OK, zero open issues and zero hotspots.
  • Guide examples and negative mutations pass; the host-dependent control-plane fragment has an explicit skip. Vale checks both public file types with zero alerts.

Ground Control Checks

  • Current-head repository policy and required CI checks pass.
  • Read-only maintainer review completed; remediation addresses the findings on the existing PR branch.

Traceability

  • IMPLEMENTS: docs/public/guides/cli.md, docs/public/guides/python.md, docs/public/guides/control-plane.md, docs/public/api/, tools/nox_support/config.py, tools/nox_support/test_lanes.py.
  • TESTS: implementations/python/tests/test_public_guide_examples.py, implementations/python/tests/test_repo_policy_tools.py.

Checklist

  • No runtime behavior, published schema, or release metadata changed.
  • Limits appear beside the affected examples.
  • Negative mutations check that the repaired samples detect refusal.
  • All required checks pass for the final head.

Documentation

The public guides and API references describe current behavior. The documentation style guide now names both checked extensions and the parser dependency. No runtime implementation, published schema, release version, or changelog changes.

…s in the CLI and Python guides

The CLI guide now says that each raes semantic command reads one document
as in-memory text, so a scenario with top-level imports is rejected with
exit 1 and only the generic sdl.parse diagnostic, and it points to
parse_sdl_file. It also names every command group that the CLI API
reference documents.

The CLI API reference (docs/public/api/cli.rst) gains sections for the
libvirt, corpus and runtime groups, so it covers every group that
raes_cli.main registers.

The Python guide now says that parse_sdl, given only text, raises
SDLParseError for top-level imports, and names parse_sdl_file. The rename
example runs on a scenario where the rename succeeds, and the text explains
why renaming a node that has an infrastructure entry is refused.
@Brad-Edwards Brad-Edwards changed the title docs(guides): correct the imports, rename and CLI-reference statements in the CLI and Python guides docs: correct guide examples and enforce documentation checks Nov 2, 2026
@Brad-Edwards
Brad-Edwards merged commit 027dd8f into dev Nov 3, 2026
40 checks passed
@Brad-Edwards
Brad-Edwards deleted the guides-imports-rename branch November 3, 2026 02:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants