FIX: RTD build - remove broken TOC entries, fix AML image paths, build PDF in CI#1740
Merged
Merged
Conversation
…d PDF in CI
The Read the Docs build for PyRIT has been failing silently because:
1. doc/myst.yml referenced two API pages that do not exist:
- api/pyrit_setup_initializers.md - gen_api_md.py does not emit a
separate page for pyrit.setup.initializers (its parent pyrit.setup
has its own API members, so the script doesn't expand into
submodules)
- api/pyrit_ui.md - the pyrit/ui/ module doesn't exist
Both entries produced RTD-fatal 'Table of contents entry does not exist'
errors (added in microsoft#1469 and microsoft#1472 in March 2026).
2. The AML troubleshooting notebooks under doc/getting_started/troubleshooting/
referenced images via ./../../assets/aml_*.png which resolves to doc/assets/
(a directory that doesn't exist). The paired .py files correctly used
./../../../assets/ (3 ../, resolving to the repo-root assets/ where the
images actually live). The .ipynb / .py pair was out of sync. The missing
images caused xdvipdfmx to abort during the PDF export on RTD.
3. The build-book GitHub Actions workflow only ran 'jupyter-book build --all
--html' (HTML-only), so PDF-only regressions silently slipped past CI
while RTD failed.
This change:
- removes the two missing TOC entries from doc/myst.yml
- syncs the .ipynb AML image paths to ./../../../assets/ matching the .py
files
- adds a 'docs-build-all' Makefile target that runs HTML + PDF together
(mirroring RTD's 'jupyter-book build --all' behaviour)
- updates .github/workflows/docs.yml to install texlive-xetex / latexmk
and use 'make docs-build-all' so PDF regressions are caught in CI
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
romanlutz
added a commit
to romanlutz/PyRIT
that referenced
this pull request
May 18, 2026
…ions Closes microsoft#1741. Append '--strict' to both 'docs-build' and 'docs-build-all' in the Makefile so MyST errors (broken links, missing TOC entries, malformed syntax, etc.) hard-fail CI instead of being silently emitted as '⛔' lines in a green build. This is how RTD silently broke before PR microsoft#1740. To make '--strict' actually pass today, add a small, well-documented 'error_rules' block to 'doc/myst.yml' that ignores three categories of errors which are inherently outside the project's control or intentionally non-resolvable: 1. 'tex-renders' (blanket): mystmd v2.x has no LaTeX renderer for the MyST layout directives the project uses extensively ('grid', 'tabSet', 'details', 'mermaid'). They render fine in HTML. PDF export emits 'Unhandled LaTeX conversion for node of X' per node. Remove when upstream support lands. 2. 'link-resolves' for auth-required external API docs: 'platform.openai.com/**', 'api.openai.com/**', 'cognitiveservices.azure.com/**'. These always return 401/403 from CI. URLs themselves are correct, just unverifiable without credentials. 3. 'link-resolves' for intentional placeholder URLs: 'pyrit.shared.foo' (style-guide example), 'account.blob.core.windows.net/...' (docstring placeholder shape), 'PyRIT/releases/vx.y.z/**' (release-process template that operators substitute at release time). 4. 'link-resolves' for stale URLs in immutable historical blog posts and one current memory doc whose external target moved ('PyRIT/.../pdf_converter.ipynb' was deleted, 'microsoft.github.io/PyRIT/**' old paths from before the v2 site restructure, 'dbeaver.com/.../sqlite.html' link rot). Marked TODO for editorial cleanup in a follow-up. Each suppression carries a comment explaining *why* the URL is suppressed and what would need to change to remove the suppression, so the allow-list stays honest. Verified locally: - 'cd doc && jupyter-book build --all --html --strict' → exit 0 - Same with a deliberately broken link added to 'doc/index.md': → exit 1, error reported, build stops. Confirms '--strict' is effective. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
hannahwestra25
approved these changes
May 18, 2026
romanlutz
added a commit
to romanlutz/PyRIT
that referenced
this pull request
May 18, 2026
The merge brought in main's docs-build-all (from PR microsoft#1740) while our branch already had it (since we merged the same PR microsoft#1740 branch earlier). The duplicate-second-wins behavior of make would have silently dropped --strict from docs-build-all. Removed the duplicate (without --strict). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The Read the Docs build for PyRIT has been failing silently for ~2 months. Most recent failed build: https://readthedocs.org/projects/pyrit/builds/32530550/
GitHub Actions kept passing because it only ran the HTML-only build, while RTD runs HTML + PDF and is stricter about TOC / image errors.
Root causes
Broken TOC entries in
doc/myst.yml(added in DOC improve API reference accuracy, structure, and readability #1469 and DOC: Add bibliography support with BibTeX citations across documentation #1472 in March 2026):api/pyrit_setup_initializers.md—gen_api_md.pydoesn't emit a separate page forpyrit.setup.initializersbecause the parentpyrit.setuphas its own API members (the script only expands "pure-aggregate" modules into submodule pages).api/pyrit_ui.md—pyrit/ui/doesn't exist in the codebase.Both produced RTD-fatal
Table of contents entry does not existerrors.Out-of-sync
.ipynbAML image paths. The AML troubleshooting notebooks underdoc/getting_started/troubleshooting/referenced./../../assets/aml_*.png(2../), which resolves todoc/assets/— a directory that doesn't exist. The paired.pyfiles correctly used./../../../assets/(3../), which resolves to the repo-rootassets/directory where the images actually live. The missing images causedxdvipdfmx:fatal: Image inclusion failedduring the PDF export on RTD, andCannot find imageerrors in the HTML build.GH Actions docs build was HTML-only.
make docs-buildrunsjupyter-book build --all --html, so PDF-only regressions silently slipped past CI while RTD failed.Changes
doc/myst.yml— removed the two missing TOC entries..ipynbfiles underdoc/getting_started/troubleshooting/— synced AML image paths to./../../../assets/so they match the.pyversions and correctly resolve to the repo-rootassets/directory.Makefile— added a newdocs-build-alltarget that mirrors RTD (jupyter-book build --all --html --pdf). Kept the existingdocs-build(HTML-only) for fast local dev iteration since most contributors don't havexelatex/latexmkinstalled..github/workflows/docs.yml— installstexlive-xetex/latexmkand usesmake docs-build-allso PDF regressions are caught in CI from now on.Verification
make docs-buildlocally — HTML build now reports 0Table of contents entry does not existerrors and 0Cannot find imageerrors (vs. 2 and 8 respectively onmain).Link has no URLerrors incode/converters/*.ipynbfrom<a id=...>HTML anchors are pre-existing and out of scope here; they were present on every prior build too.Notes for review
--strictin the future.