FIX: Backport minimal RTD config fixes so v0.12.1 builds on RTD

The v0.12.1 release tag predates every RTD fix that landed on main
(#1673, #1676, #1682, #1740, #1745, #1793, #1825), so RTD could not
build v0.12.1 from the tag. This commit backports only the surgical
changes needed to make the v0.12.1 content build under the current
RTD environment. After this lands, RTD's v0.12.1 version is
reconfigured to track this branch rather than the immutable tag.

Same pattern as the v0.13.0 backport on releases/v0.13.0.

1. .readthedocs.yaml -- the tag's config had three issues that
   combined to make RTD fail before producing any output:
     * build.jobs.build.commands is not a valid key (RTD only accepts
       html/pdf/epub/htmlzip under build.jobs.build). This was a hard
       config-validation error that aborted the build immediately.
     * When build.jobs is defined, RTD ignores the legacy python.install
       block, so dependencies were never installed and the pre_build
       step would have failed on 'ModuleNotFoundError: No module named
       griffe'. Fixed by adding an explicit build.jobs.install step
       running pip install .[dev] -- v0.12.1 uses
       [project.optional-dependencies], not PEP 735 [dependency-groups]
       -- and dropping the dead python.install block.
     * jupyter-book build --all builds frontmatter exports only (PDF
       per doc/myst.yml), not the static HTML site. --html is required
       to produce _build/html/index.html, which is what RTD serves.
       Also fixed the cp source to point at _build/html/ instead of
       _build/site/.

2. doc/myst.yml -- removes the api/pyrit_setup_initializers.md TOC
   entry. gen_api_md.py does not emit this page because pyrit.setup
   has its own API members and the script only expands pure-aggregate
   modules. Unlike at v0.13.0, api/pyrit_ui.md IS generated for v0.12.1
   (the pyrit/ui/ subpackage still existed in this tree) so that TOC
   entry is kept.

3. doc/getting_started/troubleshooting/{deploy_hf_model_aml,download_and_register_hf_model_aml,score_aml_endpoint}.ipynb
   -- correct the AML image relative paths from ./../../assets/ to
   ./../../../assets/. The paired .py source-of-truth files already
   use the correct 3-up path, and these notebooks have been
   out-of-sync with their source since before v0.12.0. Same fix that
   landed on main in PR #1740.

Verified locally: pip install .[dev] + pre_build + build produce
doc/_build/html/index.html (196 KB) and 1871 site files, with all
'Cannot find image' warnings gone.

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

Author: romanlutz

.readthedocs.yaml

@@ -11,19 +11,22 @@ build:
     python: "3.13"
     nodejs: "20"
   jobs:
+    install:
+      # When build.jobs is defined, RTD ignores the legacy python.install
+      # block (below), so dependencies must be installed explicitly here.
+      # v0.12.1 uses [project.optional-dependencies] (dev extra), not the
+      # PEP 735 [dependency-groups] introduced on main after the tag.
+      - pip install ".[dev]"
     pre_build:
       - python build_scripts/pydoc2json.py pyrit --submodules -o doc/_api/pyrit_all.json
       - python build_scripts/gen_api_md.py
     build:
       html:
-        - cd doc && jupyter-book build --all
-      commands:
+        # --all builds frontmatter exports (PDF, per doc/myst.yml); --html is
+        # required to produce the static HTML site (_build/html/index.html)
+        # that RTD serves. The 3 commands previously sat in a separate
+        # `commands:` block, which is not a valid `build.jobs.build` key in
+        # RTD and caused config validation to fail before any commands ran.
+        - cd doc && jupyter-book build --all --html
         - mkdir -p $READTHEDOCS_OUTPUT/html
-        - cp -r doc/_build/site/* $READTHEDOCS_OUTPUT/html/
-
-python:
-   install:
-   - method: pip
-     path: .
-     extra_requirements:
-         - dev
+        - cp -r doc/_build/html/* $READTHEDOCS_OUTPUT/html/

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,8 +201,6 @@ 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