Repository navigation
MAINT: Fix documentation publishing and API reference rendering - #4262
Open
Roman Lutz (romanlutz) wants to merge 13 commits into
Open
Roman Lutz (romanlutz) wants to merge 13 commits into
Roman Lutz (romanlutz) wants to merge 13 commits into
Conversation
Remove the unused PDF export, checked PDF builder, dedicated Make targets, and PDF-only guidance and error suppression. Keep Pages rendering explicitly HTML-only, including frozen release builds, with focused build contracts. Co-authored-by: Copilot App <[email protected]>
Co-authored-by: Copilot App <[email protected]>
Guard Pages recovery against ambiguous deployment state and superseded runs. Correct generated API anchors, overload documentation, field sections, headings and explicit references. Preserve notebook IDs, outputs and valid Jupytext metadata while retaining the strict locked CLI link checker. Co-authored-by: Copilot App <[email protected]>
Keep union annotations, description text and defaults inside their Markdown table cells. Cover optional constructor annotations and already escaped pipes with rendered-table regression assertions. Co-authored-by: Copilot App <[email protected]>
Leave unknown table types blank instead of rendering empty backticks. Keep video remix notes outside constructor parameter parsing and preserve literal Prompt Shield examples in code blocks. Cover these issues with renderer and source-extraction regressions. Co-authored-by: Copilot App <[email protected]>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The deployment helper incorrectly assumes the Pages deployment ID matches the source SHA, causing misleading diagnostics and preventing recovery from recognizing terminal states when the IDs differ.
1 open issue
What changed in this PR
This PR makes PyRIT’s documentation publishing HTML-only and improves generated API references, documentation links, and notebook preservation.
Changes:
- Removes PDF build support and adds Pages deployment checks, diagnostics, and recovery guidance.
- Corrects API anchors, heading hierarchy, table rendering, and docstring extraction.
- Repairs documentation references and preserves notebook cell IDs, outputs, and pairing metadata.
| File | Description |
|---|---|
tests/unit/build_scripts/test_pydoc2json.py |
Tests overload validation and docstring preservation. |
tests/unit/build_scripts/test_gen_api_md.py |
Tests table rendering and case-distinct anchors. |
tests/unit/build_scripts/test_docs_workflow.py |
Checks HTML-only publishing and recovery configuration. |
tests/unit/build_scripts/test_docs_javascript.py |
Includes deployment checks in JavaScript test coverage. |
tests/unit/build_scripts/test_docs_identifiers.py |
Checks notebook ID and output preservation settings. |
tests/unit/build_scripts/test_docs_deployment.cjs |
Tests deployment ordering and recovery guards. |
tests/unit/build_scripts/test_docs_build_contract.py |
Checks HTML configuration and notebook pairing behavior. |
tests/unit/build_scripts/test_doc_heading_hierarchy.py |
Tests generated and authored heading structure. |
tests/unit/build_scripts/test_build_docs_pdf.py |
Removes obsolete PDF build tests. |
pyrit/score/scorer_evaluation/scorer_metrics.py |
Labels documented fields as attributes. |
pyrit/score/scorer_evaluation/scorer_evaluator.py |
Labels dataset configuration fields as attributes. |
pyrit/score/scorer_evaluation/human_labeled_dataset.py |
Corrects field documentation and type notation. |
pyrit/prompt_target/prompt_shield_target.py |
Fences examples to preserve literal prompt tags. |
pyrit/prompt_target/openai/openai_video_target.py |
Moves remix guidance out of parameter documentation. |
pyrit/models/harm_definition.py |
Documents model fields as typed attributes. |
pyrit/message_normalizer/generic_system_squash.py |
Fences instruction tags to avoid unintended headings. |
pyrit/memory/memory_models.py |
Labels ORM field documentation as attributes. |
Makefile |
Removes PDF and combined-export targets. |
doc/myst.yml |
Removes PDF configuration and LaTeX warning suppression. |
doc/getting_started/troubleshooting/hf_aml_model_endpoint_guide.md |
Corrects an internal fragment link. |
doc/getting_started/troubleshooting/guide_hf_azureml.md |
Flattens subsections while retaining explicit targets. |
doc/getting_started/configuration.md |
Adds a persistent-setup reference label. |
doc/contributing/7_notebooks.md |
Documents HTML builds and notebook metadata preservation. |
doc/contributing/10_release_process.md |
Adds Pages deployment recovery instructions. |
doc/contributing/1_git.md |
Adds explicit labels for setup approaches. |
doc/code/targets/10_3_websocket_copilot_target.py |
Adds authentication section labels to the paired source. |
doc/code/targets/10_3_websocket_copilot_target.ipynb |
Adds matching authentication section labels. |
doc/code/targets/0_prompt_targets.md |
Adds a target-capabilities reference label. |
doc/code/scoring/1_true_false_scorers.py |
Corrects the OWASP edition and URL in documentation. |
doc/code/scoring/1_true_false_scorers.ipynb |
Applies the matching OWASP reference correction. |
doc/code/scoring/0_scoring.py |
Adds a batch-scoring label to the paired source. |
doc/code/scoring/0_scoring.ipynb |
Adds the matching batch-scoring label. |
doc/code/scenarios/1_common_scenario_parameters.py |
Adds a conversation-reporting label to the paired source. |
doc/code/scenarios/1_common_scenario_parameters.ipynb |
Adds the matching conversation-reporting label. |
doc/code/memory/3_memory_data_types.md |
Adds a component-identifiers reference label. |
doc/code/framework.md |
Adds a core-components reference label. |
doc/blog/2026_09_03_adversarial_model_selection.md |
Adds an observations section label. |
doc/blog/2026_04_14_scoring_scorers.md |
Adds a scorer-evaluation identifier label. |
build_scripts/pydoc2json.py |
Preserves additional docstring sections and validates overload parameters. |
build_scripts/gen_api_md.py |
Corrects anchors, tables, section rendering, and method headings. |
build_scripts/docs_deployment.cjs |
Adds read-only deployment preflight checks and diagnostics. |
build_scripts/build_docs_pdf.py |
Removes the PDF export helper. |
.pre-commit-config.yaml |
Preserves notebook cell IDs during cleanup. |
.github/workflows/docs.yml |
Selects HTML-only builds, retains artifacts, and adds deployment checks. |
Review effort: Balanced
Co-authored-by: Copilot App <[email protected]>
Resolve Pages IDs from the relevant run attempt's retained action log, diagnose only after deployment completes, and fail closed when identity cannot be established. Update recovery guidance and non-SHA regression fixtures. Co-authored-by: Copilot App <[email protected]>
Co-authored-by: Copilot App <[email protected]>
Co-authored-by: Copilot App <[email protected]>
Richard Lundeen (richlundeen)
left a comment
Contributor
There was a problem hiding this comment.
Two P2 issues need fixes before approval. The build-guide suggestion is nonblocking.
Find the last actual Pages deployment across positively skipped attempts and same-SHA runs while retaining fail-closed evidence checks. Correct PromptMemoryEntry attribute documentation and put contributor HTML build steps ahead of troubleshooting. Co-authored-by: Copilot App <[email protected]>
Resolve PDF helper modify/delete conflicts by retaining the intentional PDF removal. Preserve current upstream cache security, pinned theme tooling and dependency updates. Co-authored-by: Copilot App <[email protected]>
Move the renderer fixture into an explicit build_scripts integration batch and adjust its repository root for the new location. Preserve all existing renderer assertions and batch coverage checks. Co-authored-by: Copilot App <[email protected]>
This branch has not been deployed
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
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.

Description
Make documentation publishing explicitly HTML-only and correct misleading generated API references and notebook links. Keep deployment recovery conservative without hiding remaining build warnings.
make docs-htmlorjupyter-book build --htmlinstead of the removed PDF/all-export targets.PromptTarget | Nonenow stays entirely in the Type column instead of splitting into Description. Keep video workflow notes out of parameter rows and literal prompt tags visible.one.ipynb#0andtwo.ipynb#0now reliably reach their respective notebooks, including output/caption targets, without changing source IDs, explicit labels, HTML anchors, metadata, or saved outputs.Safe transient retries remain unresolved: the supported checker discards original
Retry-Afterheaders and exposes no per-request timeout. Native strict CLI link checking remains unchanged, and the rejected probe-based retry design is excluded. Upstream Jupytext metadata-reader warnings and residual static-parser diagnostics for forwarded parameters and legacy generics are documented, not suppressed. Pages guards support recovery but do not prevent service stalls.