Locally hosting prefect SDK reference docs for specific versions with mdxify

[kevingrismore]

Wanted to share a little thing I put together in case anyone wants to construct SDK reference docs for a particular version of prefect.

sh serve_prefect_sdk_docs.sh <optional-prefect-version-number>

Prerequisites:

• npm and node.js
• uv
• The following script, saved and aliased however you want

#!/bin/bash
set -euo pipefail

if [ "$#" -eq 0 ]; then
  echo "No Prefect version specified. Using latest."
  PREFECT_SPEC="prefect"
else
  PREFECT_SPEC="prefect==$1"
fi

echo "Using Prefect spec: $PREFECT_SPEC"

# Track initial working directory
ROOT_DIR="$(pwd)"

# Define cleanup function
cleanup() {
  echo ""
  echo "Cleaning up generated files..."
  rm -rf "$ROOT_DIR/docs"
  echo "Cleanup complete."
}
# Register trap for exit and interrupt signals
trap cleanup EXIT INT TERM

echo "Setting up docs directory..."
mkdir -p docs

cat > docs/docs.json <<EOF
{
    "\$schema": "https://mintlify.com/docs.json",
    "theme": "mint",
    "name": "Prefect",
    "colors": {
      "primary": "#2D6DF6",
      "light": "#5F92FF",
      "dark": "#2D6DF6"
    },
    "navigation": {
      "tabs": [
        {
          "tab": "Prefect SDK Reference",
          "groups": [
                {
                    "group": "Python SDK Reference",
                    "pages": ["index"]
                }
            ]
        }
      ]
    }
}
EOF

echo "Running mdxify with $PREFECT_SPEC..."
uvx --with "$PREFECT_SPEC" --with mdxify mdxify --all --root-module prefect --output-dir docs/python --anchor-name "Python SDK Reference" --exclude prefect.agent --include-inheritance

echo "Starting Mintlify dev server..."
cd docs && npx mint dev

Usage examples

Select a prefect version

sh serve_prefect_sdk_docs.sh 3.1.6

Current prefect version

Not supplying a version number will serve docs for the latest version.
sh serve_prefect_sdk_docs.sh

Ctrl+C will shut off the mintlify dev server and clean up any generated files.

Known issues and limitations:

• Only works with prefect versions >=3.1.6 due to pydantic compatibility issues.
• Docs search does not work on mintlify dev servers.