Docs guardrails

[johnjasa]

Add documentation consistency guardrails

Add model, path, model-page, and example-folder consistency tests for documentation. Run them on docs-only pull requests, add a weekly external-link check, and generate the model registry and class hierarchy automatically during docs builds without tracking generated files.

Section 1: Type of Contribution

• Documentation Update
• CI Changes

Section 2: Draft PR Checklist

• Open draft PR
• Describe the feature that will be added
• Fill out TODO list steps
• Describe requested feedback from reviewers on draft PR
• Complete Section 8: New Model Checklist (if applicable)

TODO:

N/A

Type of Reviewer Feedback Requested (on Draft PR)

Structural feedback: N/A

Implementation feedback: N/A

Other feedback: N/A

Section 3: General PR Checklist

• PR description thoroughly describes the changes.
• Added tests for documentation consistency.
• Tests pass.
• Documentation
  • Docstrings are up-to-date (not applicable)
  • Related docs/ files are up-to-date.
  • Documentation has been rebuilt successfully.
  • Examples have been updated (not applicable)
• CHANGELOG.md (not applicable)

Section 4: Related Issues

N/A

Section 5: Impacted Areas of the Software

Section 5.1: New Files

• test/test_docs_consistency.py: Guard model names, repository paths, narrative model coverage, and example-folder references.
• .github/workflows/docs.yml: Run consistency checks on relevant PRs and linkcheck weekly.

Section 5.2: Modified Files

• docs/build_book.sh, docs/generate_model_overview.py, docs/_toc.yml, and docs/user_guide/model_overview.md: Generate and navigate to the model catalog at build time.
• docs/generate_class_hierarchy.py and docs/developer_guide/class_structure.md: Generate the hierarchy automatically and remove manual-run instructions.
• docs/_config.yml: Ignore only external hosts that block automated link checks.
• .gitignore and .github/PULL_REQUEST_TEMPLATE.md: Keep generated artifacts out of Git and remove manual-generation checklist steps.
• docs/ model references and relevant model docstrings: Fix broken links found by the checker.

Section 6: Additional Supporting Information

Known gaps are explicit allowlists so newly undocumented models, examples, or paths fail the consistency test. Both generated artifacts are ignored and created by docs/build_book.sh before Jupyter Book runs. Publisher endpoints that reject crawlers are narrowly excluded from linkcheck.

Section 7: Test Results, if applicable

• python -m pytest test/test_docs_consistency.py -q: 4 passed.
• bash docs/build_book.sh: passed.
• bash docs/build_book.sh --builder linkcheck: passed.
• Pre-commit checks on changed PR B files: passed.

Section 8 (Optional): New Model Checklist

N/A

[coveralls]

Coverage is 81.152% — docs_guardrails into docs_reorg. No base build found for docs_reorg.