docs: generate the Markdown reference on release and remove HogRef generation

.github/workflows/generate-references.yml

@@ -0,0 +1,64 @@
+name: Generate references
+
+# Regenerates references/ by hand, for when the release's best-effort reference step fails
+# or the pages need a refresh. Same shape as posthog-js's generate-references.yml.
+on:
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  generate-references:
+    name: Generate SDK reference
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Get GitHub App token
+        id: releaser
+        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
+        with:
+          client-id: ${{ secrets.GH_APP_POSTHOG_PYTHON_RELEASER_APP_ID }}
+          private-key: ${{ secrets.GH_APP_POSTHOG_PYTHON_RELEASER_PRIVATE_KEY }}
+
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+          token: ${{ steps.releaser.outputs.token }}
+
+      - name: Check out sdk-specs
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: PostHog/sdk-specs
+          path: .sdk-specs
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: 3.11
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          version: "0.13.4"
+          enable-cache: true
+
+      - name: Generate references
+        id: changes
+        run: |
+          uv run --extra dev bin/docs --sdk-specs .sdk-specs
+          git add references
+          git diff --cached --quiet || echo "changed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Commit generated references
+        if: steps.changes.outputs.changed == 'true'
+        uses: planetscale/ghcommit-action@a6b150b81dca5dd027baa898604418eec9e11465 # v0.2.22
+        with:
+          commit_message: "docs: update the SDK reference [skip ci]"
+          repo: ${{ github.repository }}
+          branch: main
+          file_pattern: references/
+        env:
+          GITHUB_TOKEN: ${{ steps.releaser.outputs.token }}

.github/workflows/release.yml

@@ -177,10 +177,28 @@ jobs:
           git fetch origin main
           git reset --hard "$COMMIT_HASH"
 
+      # The reference headings come from the sdk-specs capabilities.
+      - name: Check out sdk-specs
+        # Best-effort: a failure never blocks the release. Run generate-references.yml to retry.
+        continue-on-error: true
+        if: steps.commit-release.outputs.commit-hash != ''
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: PostHog/sdk-specs
+          path: .sdk-specs
+          persist-credentials: false
+
       - name: Generate references
+        id: reference
+        # Best-effort: a failure never blocks the release. Run generate-references.yml to retry.
+        continue-on-error: true
         if: steps.commit-release.outputs.commit-hash != ''
         run: |
-          uv run bin/docs generate-references
+          uv run bin/docs --sdk-specs .sdk-specs
+
+      - name: Warn if the SDK reference didn't regenerate
+        if: steps.reference.outcome == 'failure'
+        run: echo "::warning::The SDK reference didn't regenerate. Run generate-references.yml to retry."
 
       - name: Check for changes in references
         if: steps.commit-release.outputs.commit-hash != ''

bin/docs

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
-#/ Usage: bin/docs
-#/ Description: Generate documentation for the PostHog Python SDK
+#/ Usage: bin/docs --sdk-specs <PostHog/sdk-specs checkout>
+#/ Description: Generate the Markdown reference for the PostHog Python SDK
 source bin/helpers/_utils.sh
 set_source_and_root_dir
 ensure_virtual_env
 
-exec python3 "$(dirname "$0")/docs_scripts/generate_json_schemas.py" "$@" 
+exec python3 "$(dirname "$0")/docs_scripts/generate_markdown.py" "$@"