[docs] include sphinx objects.inv in yarn build-api-docs (#27906)

## Summary & Motivation

Consolidate `yarn build-sphinx-objects-inv` and `yarn sync-api-docs`
into a single `yarn build-api-docs`.

## How I Tested These Changes

## Changelog

NOCHANGELOG

docs/.gitignore

@@ -1,6 +1,9 @@
 # code examples are generated at run and build time, and should not be included in version control
 src/code-examples-content.js
 
+# this file is generated at build time with `yarn build-api-docs`
+static/objects.inv
+
 sphinx/_build/
 .env
 .docusaurus

docs/Makefile

@@ -24,7 +24,7 @@ mdx_copy:
 
 sphinx_objects_inv:
 	@echo "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
-	@echo "DEPRECATED - use \`yarn build-sphinx-object-inv\`"
+	@echo "DEPRECATED - use \`yarn build-api-docs\`"
 	@echo "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
 	tox -e sphinx
 	cp sphinx/_build/json/objects.inv static/.

docs/README.md

@@ -58,12 +58,9 @@ This command starts a local development server and opens [http://localhost:3050]
 To build the site for production:
 
 ```bash
-# build and copy api markdown files
+# build and copy API markdown files; build and copy the sphinx `objects.inv` to static/
 yarn build-api-docs
 
-# build and copy the sphinx objects.inv
-yarn build-sphinx-object-inv
-
 # build the static site
 yarn build
 ```

docs/package.json

@@ -17,10 +17,9 @@
     "lint": "eslint . --ext=.tsx,.ts,.js,.md,.mdx --ignore-pattern 'node_modules/*' --ignore-pattern 'versioned_docs/*' --ignore-pattern 'versioned_sidebars/*' --fix",
     "lint-and-vale": "yarn run lint && yarn run vale",
     "generate-code-imports": "node scripts/generate-code-imports.js",
-    "sync-api-docs": "/bin/sh scripts/vercel-sync-api-docs.sh",
-    "build-api-docs": "tox -e sphinx-mdx && cp -rf sphinx/_build/mdx/sections/api/apidocs/* docs/api/python-api/",
-    "build-sphinx-object-inv": "tox -e sphinx && cp sphinx/_build/json/objects.inv static/.",
-    "rebuild-kinds-tags": "python scripts/rebuild-kinds-tags.py"
+    "rebuild-kinds-tags": "python scripts/rebuild-kinds-tags.py",
+    "sync-api-docs": "/bin/sh scripts/build-api-docs.sh",
+    "build-api-docs": "/bin/sh scripts/build-api-docs.sh"
   },
   "dependencies": {
     "@docusaurus/core": "^3.7.0",

docs/scripts/build-api-docs.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+#
+# Builds and synchronizes mdx API docs, and objects.inv using Sphinx
+#
+# USAGE
+#
+#     yarn build-api-docs
+#
+
+set -e
+
+# Vercel-specific commands and configurations
+if ! [[ "$OSTYPE" =~ "darwin"* ]]; then
+  echo "Detected non-Darwin host. Running Vercel-specific commands and configurations"
+
+  # Required to resolve `locale.Error: unsupported locale setting`
+  export LC_ALL=C.UTF-8
+
+  if ! command -v uv &> /dev/null; then
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+
+    # shellcheck source=/dev/null
+    source "$HOME/.local/bin/env"  
+  fi
+
+  uv python install 3.11
+  uv venv
+  source .venv/bin/activate
+  uv pip install tox
+fi
+
+echo "Running sphinx-mdx and copying files to \`docs/api/python-api\`"
+tox -e sphinx-mdx
+cp -rf sphinx/_build/mdx/sections/api/apidocs/* docs/api/python-api/
+
+echo "Running sphinx and copying \`object.inv\` to \`static/\`"
+tox -e sphinx
+cp sphinx/_build/json/objects.inv static/.