FIX Restore docs build validation

[hannahwestra25]

Root cause

Lazy package exports made the aggregate pyrit JSON contain both direct members and submodules. _expand_module() stopped at the parent as soon as it saw direct API, so generation emitted only api/pyrit.md and failed TOC validation. Separately, the docs workflow always checked out each configured ref, so pull requests validated the base branch rather than their merge revision.

Behavior change

• Expand mixed aggregate modules to the existing public API page frontier while retaining unique direct API and removing symbols already represented by descendant package pages.
• On pull requests, replace the configured matrix entry matching github.base_ref with github.sha. Main PRs replace latest; release PRs replace their release entry. Missing or unconfigured base refs fail explicitly.
• Preserve configured refs for push and workflow-dispatch builds.
• Add focused regression coverage for mixed module expansion, duplicate suppression, main/release PR targeting, invalid PR bases, and non-PR behavior.

Validation

• python -m pytest tests\unit\build_scripts\test_gen_api_md.py tests\unit\build_scripts\test_resolve_docs_matrix.py -q — 63 passed
• python -m ruff check ... and python -m ruff format --check ... — passed
• ty check ... — passed (repository-config compatibility warnings only)
• Parsed .github/workflows/docs.yml with PyYAML
• Exercised main-target, release-target, push, missing-base, and unconfigured-base matrix resolution locally
• python -m build_scripts.pydoc2json pyrit --submodules -o doc\_api\pyrit_all.json
• python -m build_scripts.gen_api_md — generated the expected 27 pages; TOC and orphan validation passed