[DRAFT] DOC Add API example backlinks

[hugosmoreira]

Description

Closes #654.

PyRIT's documentation has moved from the Sphinx-based setup described in the original issue to Jupyter Book 2/MyST and the custom gen_api_md.py generator. This updates that generator to build API-to-guide backlinks automatically:

• scan only published user-guide pages from doc/myst.yml
• parse Jupytext companions, standalone notebooks, and Markdown Python fences without executing documentation code
• link classes and top-level functions only when they are imported and actually referenced
• handle aliases, module imports, deep implementation imports, ambiguity, deduplication, and deterministic ordering
• render an Examples list on the matching API class/function section

Jupytext .py companions are used as the analysis source while the generated links continue to point to their .ipynb pages.

The analysis is intentionally conservative: star/dynamic imports and instance-method type inference are not guessed. Invalid illustrative snippets are skipped so they cannot break API generation.

Tests and Documentation

• python -m pytest tests/unit/build_scripts/test_gen_api_md.py -q --confcutdir=tests/unit/build_scripts — 39 passed
• ruff check build_scripts/gen_api_md.py tests/unit/build_scripts/test_gen_api_md.py
• ruff format --check build_scripts/gen_api_md.py tests/unit/build_scripts/test_gen_api_md.py
• ty check build_scripts/gen_api_md.py tests/unit/build_scripts/test_gen_api_md.py
• generated the real API reference with pydoc2json.py and gen_api_md.py
• validated all 157 myst.yml references
• verified all 668 generated example links resolve to existing local documentation pages
• reran generation and confirmed deterministic output

No documentation source notebooks changed, so Jupytext execution was not applicable.

Disclosure: I used Codex as a coding assistant while implementing and validating this change. I reviewed the patch and generated output and will own any follow-up changes from review.

[hugosmoreira]

@microsoft-github-policy-service agree