Generate reference documentation at publish-time and the JSON schema at release-time (#16969)

It'd be nice to avoid churn for contributors. This is a pretty frequent
cause of CI failures and I don't think we really need to have the
reference documentation committed.

.github/workflows/ci.yml

@@ -27,6 +27,8 @@ jobs:
     outputs:
       # Flag that is raised when any code is changed
       code: ${{ steps.changed.outputs.code_any_changed }}
+      # Flag that is raised when uv.schema.json is changed (e.g., in a release PR)
+      schema: ${{ steps.changed.outputs.schema_changed }}
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
@@ -40,10 +42,16 @@ jobs:
           CHANGED_FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha || 'origin/main' }}...HEAD)
 
           CODE_CHANGED=false
+          SCHEMA_CHANGED=false
 
           while IFS= read -r file; do
-            # Generated markdown and JSON files are checked during test runs.
+            # Check if the schema file changed (e.g., in a release PR)
-            if [[ "${file}" =~ ^docs/ && ! "${file}" =~ ^docs/reference/(cli|settings).md && ! "${file}" =~ ^docs/reference/environment.md ]]; then
+            if [[ "${file}" == "uv.schema.json" ]]; then
+              echo "Detected schema change: ${file}"
+              SCHEMA_CHANGED=true
+            fi
+
+            if [[ "${file}" =~ ^docs/ ]]; then
               echo "Skipping ${file} (matches docs/ pattern)"
               continue
             fi
@@ -70,6 +78,7 @@ jobs:
 
           done <<< "${CHANGED_FILES}"
           echo "code_any_changed=${CODE_CHANGED}" >> "${GITHUB_OUTPUT}"
+          echo "schema_changed=${SCHEMA_CHANGED}" >> "${GITHUB_OUTPUT}"
   lint:
     timeout-minutes: 10
     name: "lint"
@@ -208,7 +217,12 @@ jobs:
         with:
           save-if: ${{ github.ref == 'refs/heads/main' }}
       - name: "Generate all"
-        run: cargo dev generate-all --mode check
+        run: cargo dev generate-all --mode dry-run
+      - name: "Check sysconfig mappings"
+        run: cargo dev generate-sysconfig-metadata --mode check
+      - name: "Check JSON schema"
+        if: ${{ needs.determine_changes.outputs.schema == 'true' }}
+        run: cargo dev generate-json-schema --mode check
 
   cargo-shear:
     timeout-minutes: 10
@@ -510,6 +524,14 @@ jobs:
           version: "0.9.13"
 
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+      - uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0 # v2.8.0
+        with:
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+      - name: "Generate reference documentation"
+        run: |
+          cargo dev generate-options-reference
+          cargo dev generate-cli-reference
+          cargo dev generate-env-vars-reference
       - name: "Add SSH key"
         if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
         uses: webfactory/ssh-agent@a6f90b1f127823b31d4d4a8d96047790581349bd # v0.9.1

.github/workflows/publish-docs.yml

@@ -36,6 +36,14 @@ jobs:
         with:
           python-version: 3.12
 
+      - uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0 # v2.8.0
+
+      - name: "Generate reference documentation"
+        run: |
+          cargo dev generate-options-reference
+          cargo dev generate-cli-reference
+          cargo dev generate-env-vars-reference
+
       - name: "Set docs display name"
         run: |
           version="${VERSION}"

.gitignore

@@ -37,6 +37,11 @@ profile.json.gz
 # MkDocs
 /site
 
+# Generated reference docs (use `cargo dev generate-all` to regenerate)
+/docs/reference/cli.md
+/docs/reference/environment.md
+/docs/reference/settings.md
+
 # macOS
 **/.DS_Store
 

scripts/release.sh

@@ -22,3 +22,6 @@ uv run "$project_root/scripts/generate-crate-readmes.py"
 echo "Updating lockfile..."
 cargo update -p uv
 pushd crates/uv-trampoline; cargo update -p uv-trampoline; popd
+
+echo "Generating JSON schema..."
+cargo dev generate-json-schema