Skip to content

MAINT: Fix documentation publishing and API reference rendering - #4262

Open
Roman Lutz (romanlutz) wants to merge 13 commits into
microsoft:mainfrom
romanlutz:romanlutz-honest-docs-export-results
Open

Roman Lutz (romanlutz) wants to merge 13 commits into
microsoft:mainfrom
romanlutz:romanlutz-honest-docs-export-results

Conversation

@romanlutz

@romanlutz Roman Lutz (romanlutz) commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

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.

  • Remove unused PDF export configuration, helper and Make targets. Use make docs-html or jupyter-book build --html instead of the removed PDF/all-export targets.
  • Guard Pages publishing against superseded runs and ambiguous deployment states, track actual Pages deployment IDs for recovery, retain composed artifacts for seven days, and document native failed-job recovery.
  • Give case-colliding API symbols distinct anchors, nest method headings correctly, preserve Attributes/Type Parameters/prose, and validate overload documentation without changing runtime signatures.
  • Escape table-cell pipes and avoid empty code spans: PromptTarget | None now stays entirely in the Type column instead of splitting into Description. Keep video workflow notes out of parameter rows and literal prompt tags visible.
  • Namespace legacy numeric notebook reference IDs before MyST resolves links. one.ipynb#0 and two.ipynb#0 now reliably reach their respective notebooks, including output/caption targets, without changing source IDs, explicit labels, HTML anchors, metadata, or saved outputs.
  • Correct malformed docstring sections and continuation indentation, reducing remaining extraction diagnostics from 256 to 87. Add focused extraction regressions and real-renderer reference fixtures.
  • Correct explicit documentation references and the OWASP URL; preserve valid Jupytext metadata and notebook outputs during cleanup.

Safe transient retries remain unresolved: the supported checker discards original Retry-After headers 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.

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]>
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]>
Copilot AI balanced review requested due to automatic review settings November 13, 2026 08:59

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread build_scripts/docs_deployment.cjs Resolved
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]>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two P2 issues need fixes before approval. The build-guide suggestion is nonblocking.

Comment thread build_scripts/docs_deployment.cjs Resolved
Comment thread pyrit/memory/memory_models.py Resolved
Comment thread doc/contributing/7_notebooks.md Resolved
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

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants