Repository navigation
MAINT: Fix documentation publishing and API reference rendering - #4262
Open
Roman Lutz (romanlutz) wants to merge 8 commits into
Open
Roman Lutz (romanlutz) wants to merge 8 commits into
Roman Lutz (romanlutz) wants to merge 8 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 <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
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 <223556219+Copilot@users.noreply.github.com>
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 <223556219+Copilot@users.noreply.github.com>
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 <223556219+Copilot@users.noreply.github.com>
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
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 <223556219+Copilot@users.noreply.github.com>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
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 or malformed generated API references. 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.Existing duplicate numeric notebook-ID warnings remain unresolved;
--keep-idonly prevents future churn. The unsafe identifier plugin and blocked retry-runner design are excluded, strict CLI link checking remains, and upstream metadata warnings and residual API extraction diagnostics are not suppressed. Pages guards support recovery but do not prevent service stalls.