FIX: RTD build - remove broken TOC entries, fix AML image paths, build PDF in CI (#1740)

Co-authored-by: romanlutz <romanlutz@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: romanlutz

.github/workflows/docs.yml

@@ -55,10 +55,24 @@ jobs:
     - name: Install PyRIT with uv
       run: uv sync --extra all
 
-    # Build the book
+    # LaTeX toolchain needed for the PDF export (jupyter-book --pdf via xelatex).
+    # Mirrors the ReadTheDocs build so CI catches PDF-only issues (e.g. broken
+    # image paths) instead of letting them silently break the RTD build.
+    - name: Install LaTeX (for PDF export)
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y --no-install-recommends \
+          texlive-xetex \
+          texlive-fonts-recommended \
+          texlive-fonts-extra \
+          texlive-plain-generic \
+          texlive-latex-extra \
+          latexmk
+
+    # Build the book (HTML site + PDF export)
     - name: Build the book
       run: |
-        make docs-build
+        make docs-build-all
     # Upload the book's HTML as an artifact
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v3

Makefile

@@ -20,14 +20,25 @@ ty:
 # Build the full documentation site:
 # 1. Generate API reference JSON from Python source (griffe)
 # 2. Convert API JSON to MyST markdown pages
-# 3. Build the Jupyter Book site
+# 3. Build the Jupyter Book site (HTML only — fast, no LaTeX needed)
 # 4. Generate RSS feed
 docs-build:
 	uv run python build_scripts/pydoc2json.py pyrit --submodules -o doc/_api/pyrit_all.json
 	uv run python build_scripts/gen_api_md.py
 	cd doc && uv run jupyter-book build --all --html
 	uv run ./build_scripts/generate_rss.py
 
+# Build the full documentation site including the PDF export.
+# Mirrors the ReadTheDocs build (.readthedocs.yaml) so CI catches PDF-only issues
+# such as missing images that the HTML-only build silently ignores.
+# Requires xelatex / latexmk on PATH (texlive-xetex + texlive-fonts-recommended +
+# texlive-plain-generic + latexmk on Ubuntu).
+docs-build-all:
+	uv run python build_scripts/pydoc2json.py pyrit --submodules -o doc/_api/pyrit_all.json
+	uv run python build_scripts/gen_api_md.py
+	cd doc && uv run jupyter-book build --all --html --pdf
+	uv run ./build_scripts/generate_rss.py
+
 # Regenerate only the API reference pages (without building the full site)
 docs-api:
 	uv run python build_scripts/pydoc2json.py pyrit --submodules -o doc/_api/pyrit_all.json

doc/getting_started/troubleshooting/deploy_hf_model_aml.ipynb

@@ -47,9 +47,9 @@
     "\n",
     "5. **AZURE_ML_MODEL_NAME_TO_DEPLOY**\n",
     "   - If the model is listed in the AZURE ML Hugging Face model catalog, then supply the model name as shown in the following image.\n",
-    "   <br> <img src=\"./../../assets/aml_hf_model.png\" alt=\"AML Hugging Face model\" height=\"400\"/> <br>\n",
+    "   <br> <img src=\"./../../../assets/aml_hf_model.png\" alt=\"AML Hugging Face model\" height=\"400\"/> <br>\n",
     "   - If you intend to deploy the model from the AZURE ML workspace model registry, then use the model name as shown in the subsequent image.\n",
-    "   <br> <img src=\"./../../assets/aml_ws_model.png\" alt=\"AML Workspace model\" height=\"400\"/> <br>\n",
+    "   <br> <img src=\"./../../../assets/aml_ws_model.png\" alt=\"AML Workspace model\" height=\"400\"/> <br>\n",
     "6. **AZURE_ML_MODEL_VERSION_TO_DEPLOY**\n",
     "   - You can find the details of the model version in the images from previous step associated with the respective model.\n",
     "\n",
@@ -277,7 +277,7 @@
     "**Add deployment to an Azure ML endpoint created above**\n",
     "\n",
     "Please be aware that deploying, particularly larger models, may take some time. Once the deployment is finished, the provisioning state will be marked as 'Succeeded', as illustrated in the image below.\n",
-    "<br> <img src=\"./../../assets/aml_endpoint_deployment.png\" alt=\"AML Endpoint Deployment\" height=\"400\"/> <br>"
+    "<br> <img src=\"./../../../assets/aml_endpoint_deployment.png\" alt=\"AML Endpoint Deployment\" height=\"400\"/> <br>"
    ]
   },
   {

doc/getting_started/troubleshooting/download_and_register_hf_model_aml.ipynb

@@ -127,7 +127,7 @@
     "\n",
     "9. **AZURE_ML_COMPUTE_NAME**\n",
     "   - If you already have an Azure ML compute cluster, provide its name. If not, the script will create one based on the instance size and the specified minimum and maximum instances.\n",
-    "   <br> <img src=\"./../../assets/aml_compute_cluster.png\" alt=\"AML compute cluster\" height=\"400\"/> <br>\n",
+    "   <br> <img src=\"./../../../assets/aml_compute_cluster.png\" alt=\"AML compute cluster\" height=\"400\"/> <br>\n",
     "\n",
     "10. **IDLE_TIME_BEFORE_SCALE_DOWN**\n",
     "    - Set the duration for the Azure ML cluster to remain active before scaling down due to inactivity, ensuring efficient resource use. Typically, 3-4 hours is ideal for large size models.\n",

doc/getting_started/troubleshooting/score_aml_endpoint.ipynb

@@ -25,15 +25,15 @@
     "\n",
     "1. **AZURE_ML_SCORE_DEPLOYMENT_NAME**\n",
     "   - This deployment name can be acquired from the Azure ML managed online endpoint, as illustrated in image below.\n",
-    "   <br> <img src=\"./../../assets/aml_deployment_name.png\" alt=\"AML Deployment Name\" height=\"400\"/> <br>\n",
+    "   <br> <img src=\"./../../../assets/aml_deployment_name.png\" alt=\"AML Deployment Name\" height=\"400\"/> <br>\n",
     "\n",
     "2. **AZURE_ML_MANAGED_ENDPOINT**\n",
     "   - To obtain the managed endpoint, navigate through the Azure ML workspace by selecting 'Launch Studio', then 'Endpoints' on the left side, followed by 'Consume'. Copy the REST endpoint as depicted below.\n",
-    "    <br> <img src=\"./../../assets/aml_score_uri.png\" alt=\"AML Score URI\" height=\"400\"/> <br>\n",
+    "    <br> <img src=\"./../../../assets/aml_score_uri.png\" alt=\"AML Score URI\" height=\"400\"/> <br>\n",
     "\n",
     "3. **AZURE_ML_KEY**\n",
     "   - Navigate through the Azure ML workspace by selecting 'Launch Studio', then 'Endpoints' on the left side, followed by 'Consume'. The primary key can be obtained as shown in the subsequent image.\n",
-    "   <br> <img src=\"./../../assets/aml_score_key.png\" alt=\"AML Score Key\" height=\"400\"/> <br>\n",
+    "   <br> <img src=\"./../../../assets/aml_score_key.png\" alt=\"AML Score Key\" height=\"400\"/> <br>\n",
     "\n"
    ]
   },
@@ -80,7 +80,7 @@
     "**Azure ML endpoint JSON body**\n",
     "\n",
     "The JSON body can be acquired by the following method: Access the Hugging Face model within the Azure ML model catalog by going to the workspace, then to the studio, selecting 'Model Catalog', and using the search bar to find the model ID. Open the model to view the sample input schema as shown in the image below.\n",
-    "<br> <img src=\"./../../assets/aml_model_endpoint_schema.png\" alt=\"aml_model_endpoint_schema.png\" height=\"400\"/> <br>\n",
+    "<br> <img src=\"./../../../assets/aml_model_endpoint_schema.png\" alt=\"aml_model_endpoint_schema.png\" height=\"400\"/> <br>\n",
     "\n",
     "In addition, we have compiled the details of the request and response for the Hugging Face models hosted on the Azure Machine Learning (Azure ML) endpoint. Please review the [provided link](./hf_aml_model_endpoint_guide.md) to access the JSON request body and response for the Azure ML endpoint. Additionally, you can deduce the schema from the response if a bad request was sent to the inference endpoint."
    ]

doc/myst.yml

@@ -201,10 +201,7 @@ project:
         - file: api/pyrit_scenario.md
         - file: api/pyrit_score.md
         - file: api/pyrit_setup.md
-          children:
-            - file: api/pyrit_setup_initializers.md
         - file: api/pyrit_show_versions.md
-        - file: api/pyrit_ui.md
     - file: blog/README.md
       children:
         - file: blog/2026_04_14_scoring_scorers.md