MAINT Separate strict HTML and checked PDF documentation builds

[Roman Lutz (romanlutz)]

Description

Strict documentation builds fail on a Wikipedia media-viewer fragment in the ship-photo citation. Separately, --all --html also selects the configured PDF export, so an HTML build can attempt LaTeX and report a missing book.log when the toolchain is unavailable.

• Replace the citation with the canonical Commons file page and include the photographer/crop credits in both paired notebook files. Preserve the image, executable cells, outputs, and metadata.
• Remove five unsupported :gutter: 3 options. The current MyST renderer already ignores them, so this removes warnings without changing card spacing, columns, or order.
• Make docs-build generate the API reference and run strict HTML without --all, while preserving RSS generation. Add docs-build-pdf and sequence HTML before PDF in docs-build-all.
• Check PDF prerequisites, native build failures, fresh readable PDF output, and fresh native logs without fatal LaTeX diagnostics. Include --site with --pdf --strict because the locked Jupyter Book version applies strict document-error checking to site processing, not standalone exports.

Strictness is preserved and warnings are not globally suppressed. Hosted CI, publishing settings, dependency versions, and landing-page video behavior are unchanged. Contributors who previously relied on make docs-build implicitly attempting PDF export should use make docs-build-pdf or make docs-build-all.

Tests and Documentation

Documented uv preparation, independent HTML/PDF commands, PDF prerequisites, and output acceptance checks in the notebook contribution guide. Added helper and build-contract regressions alongside existing documentation structure, workflow, and video-player tests.

Commands run from the repository root unless noted:

# Passed: 82 tests.
uv run --frozen --no-sync python -m pytest tests\unit\build_scripts\test_build_docs_pdf.py tests\unit\build_scripts\test_docs_build_contract.py tests\unit\build_scripts\test_validate_docs.py tests\unit\build_scripts\test_docs_workflow.py tests\unit\build_scripts\test_landing_video_players.py -q

# Passed: lint, formatting, and targeted type checks.
uv run --frozen --no-sync ruff check build_scripts\build_docs_pdf.py tests\unit\build_scripts\test_build_docs_pdf.py tests\unit\build_scripts\test_docs_build_contract.py doc\code\executor\8_modality_feedback.py
uv run --frozen --no-sync ruff format --check build_scripts\build_docs_pdf.py tests\unit\build_scripts\test_build_docs_pdf.py tests\unit\build_scripts\test_docs_build_contract.py
uv run --frozen --no-sync ty check build_scripts\build_docs_pdf.py tests\unit\build_scripts\test_build_docs_pdf.py tests\unit\build_scripts\test_docs_build_contract.py

# Passed: API generation, structure validation, and RSS generation (each exit 0).
uv run --frozen --no-sync python -m build_scripts.pydoc2json pyrit --submodules -o doc\_api\pyrit_all.json
uv run --frozen --no-sync python -m build_scripts.gen_api_md
uv run --frozen --no-sync python -m build_scripts.validate_docs
uv run --frozen --no-sync python -m build_scripts.generate_rss

# Passed from doc after API preparation: exit 0, fresh HTML, no LaTeX/PDF invocation.
uv run --frozen --no-sync jupyter-book build --html --strict

# Expected exit 1: explicit missing-prerequisite error for latexmk and xelatex.
uv run --frozen --no-sync python -m build_scripts.build_docs_pdf

Verified the corrected citation and photographer credit in rendered HTML, preserved landing-player assets, and unchanged notebook code, outputs, and metadata. Strict HTML still reports existing warnings; success is not a claim of warning-free documentation. Commit hooks passed.

Actual PDF compilation and PDF content/layout inspection were not run because latexmk and xelatex are unavailable. Synthetic PDFs in unit tests validate the helper's checks, not the real book export. Real PDF acceptance still requires an equipped environment.

JupyText was used to check paired cell consistency, but notebook execution was not run. No live notebook/provider calls were made.