perf(docs): pre-render API reference HTML in Python

.github/workflows/netlify-deploy-v2.yaml

@@ -44,7 +44,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: docs/versioned_docs/${{ matrix.version.section }}
-          key: version-docs-${{ matrix.version.section }}-${{ steps.sha.outputs.sha }}
+          key: version-docs-${{ hashFiles('scripts/docs/*.py', 'scripts/docs/templates/**', 'docs/*_template.md') }}-${{ matrix.version.section }}-${{ steps.sha.outputs.sha }}
       - name: Checkout
         if: steps.cache.outputs.cache-hit != 'true'
         uses: actions/checkout@v4
@@ -54,7 +54,7 @@ jobs:
       - name: Checkout branch packages
         if: steps.cache.outputs.cache-hit != 'true'
         run: |
-          git checkout origin/${{ matrix.version.branch }} -- gooddata-api-client/ packages/gooddata-sdk/ packages/gooddata-pandas/ scripts/script-requirements.txt
+          git checkout origin/${{ matrix.version.branch }} -- gooddata-api-client/ packages/gooddata-sdk/ packages/gooddata-pandas/
       - name: Setup Python
         if: steps.cache.outputs.cache-hit != 'true'
         uses: actions/setup-python@v5

.github/workflows/rw-collect-changes.yaml

@@ -40,6 +40,7 @@ jobs:
             python-modules:
               - '.docker/**'
               - 'packages/**'
+              - 'scripts/docs/**'
               - '*.mk'
               - 'Makefile'
               - Dockerfile

.github/workflows/rw-python-tests.yaml

@@ -44,6 +44,22 @@ jobs:
       - name: pep8 and formatting check
         run: |
           make format
+  docs-scripts-tests:
+    runs-on: ubuntu-latest
+    if: ${{inputs.changed-python-modules == 'true'}}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up python 3.14
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: 3.14
+      - name: Install dependencies
+        run: |
+          uv sync --group test --locked
+      - name: Test docs scripts
+        run: |
+          make test-docs-scripts
   types-check:
     runs-on: ubuntu-latest
     if: ${{inputs.changed-python-modules == 'true'}}

Makefile

@@ -108,6 +108,10 @@ remove-cassettes:
 	for project in $(NO_CLIENT_GD_PROJECTS_DIRS); do $(MAKE) -C packages/$${project} $@ || RESULT=$$?; done; \
 	exit $$RESULT
 
+.PHONY: test-docs-scripts
+test-docs-scripts:
+	uv run pytest scripts/docs/tests/ -v
+
 .PHONY: new-docs
 new-docs:
 	cd docs; \

docs/Dockerfile

@@ -7,8 +7,8 @@ RUN apt-get update && apt-get install -y git make curl
 # Copy only dependency manifests and package source before installing.
 COPY scripts/script-requirements.txt /scripts/script-requirements.txt
 COPY gooddata-api-client /gooddata-api-client
-COPY packages/gooddata-sdk /gooddata-sdk
-COPY packages/gooddata-pandas /gooddata-pandas
+COPY packages/gooddata-sdk /packages/gooddata-sdk
+COPY packages/gooddata-pandas /packages/gooddata-pandas
 
 RUN --mount=type=cache,target=/root/.cache/pip \
     pip install -r /scripts/script-requirements.txt
@@ -21,9 +21,7 @@ WORKDIR /docs
 
 RUN python json_builder.py && \
     python python_ref_builder.py api_spec.toml data.json latest content/en && \
-    mkdir versioned_docs/latest && \
-    mv -f data.json ./versioned_docs/latest/data.json && \
-    mv -f content/en/latest/links.json ./versioned_docs/latest/links.json
+    rm -f data.json
 
 FROM node:20.18.0-bookworm-slim
 
@@ -37,9 +35,9 @@ COPY --from=builder /docs /docs
 
 WORKDIR /docs
 
-# Use BuildKit cache mounts so npm/Go package downloads survive layer rebuilds
+# npm cache mount speeds up rebuilds; Go modules are stored in the image
+# layer so Hugo can resolve them at runtime.
 RUN --mount=type=cache,target=/root/.npm \
-    --mount=type=cache,target=/root/go/pkg/mod \
     npm install && \
     hugo mod get
 

docs/class_template.md

@@ -3,4 +3,4 @@ linkTitle: "LINK"
 no_list: true
 ---
 
-{{< api-ref-class "PATH" >}}
+CONTENT

docs/content/en/latest/api-reference/_index.md

@@ -4,6 +4,3 @@ linkTitle: "API Reference"
 weight: 99
 navigationLabel: true
 ---
-
-
-Placeholder for gerenerated API reference.

docs/content/en/latest/pandas/_index.md

@@ -4,6 +4,3 @@ linkTitle: "GOODDATA PANDAS"
 weight: 59
 navigationLabel: true
 ---
-
-
-Placeholder for gerenerated API reference - pandas.

docs/function_template.md

@@ -5,4 +5,4 @@ superheading: "PARENT."
 weight: 100
 ---
 
-{{< api-ref "PATH" >}}
+CONTENT

docs/module_template.md

@@ -4,4 +4,4 @@ linkTitle: "LINK"
 no_list: true
 ---
 
-{{< api-ref-module "PATH" >}}
+CONTENT

pyproject.toml

@@ -48,6 +48,8 @@ type = [
 test = [
     # Common test dependencies used across all workspace packages
     "pytest~=8.3.4",
+    # Required by scripts/docs/ tests (python_ref_builder uses toml)
+    "toml~=0.10.2",
     "pytest-cov~=6.0.0",
     "pytest-json-report==1.5.0",
     # Additional test dependencies used by multiple packages

scripts/docs/README.md

@@ -0,0 +1,87 @@
+# Documentation Generation
+
+This directory contains Python scripts that generate the API reference pages for
+the GoodData Python SDK documentation site.
+
+## How it works
+
+The docs site is built with Hugo. API reference pages are generated in two steps:
+
+1. **`json_builder.py`** — introspects the installed `gooddata_sdk` and
+   `gooddata_pandas` packages using `inspect`, producing a `data.json` file with
+   class/function/property metadata and parsed docstrings.
+2. **`python_ref_builder.py`** — reads `data.json` and `api_spec.toml`, then
+   generates markdown files with pre-rendered HTML for each module, class, and
+   function. Jinja2 templates in `templates/` replicate the output of the former
+   Hugo shortcodes, but at build time instead of at Hugo render time.
+
+The generated markdown files contain Hugo front matter (title, linkTitle, weight)
+and a `CONTENT` block with the full HTML. Hugo serves them as-is without needing
+shortcodes, `data.json`, or `links.json`.
+
+## Workflows
+
+There are three documentation deployment workflows, in order of
+preference:
+
+### 1. V2 parallel workflow (`netlify-deploy-v2.yaml`) — recommended
+
+Triggered manually via `workflow_dispatch`.
+
+```
+discover-versions ──> generate-version (matrix, parallel) ──> build-and-deploy
+```
+
+- `discover-versions.sh` finds the latest N release branches.
+- Each version runs in its own runner: checks out the version's SDK packages,
+  installs master's `script-requirements.txt`, runs `json_builder.py` +
+  `python_ref_builder.py` via `generate-single-version.sh`.
+- Per-version results are cached by `(scripts hash + templates hash + branch SHA)`.
+- `assemble-versions.sh` merges all version artifacts, promotes the highest
+  numbered version to `/latest`, then Hugo builds the final site.
+- Deploys as a Netlify **draft** (no `--prod`).
+
+### 2. Legacy single-job workflow (`netlify-deploy.yaml`) — production
+
+Triggered manually via `workflow_dispatch`.
+
+- Uses `hugo-build-versioned-action` which downloads `generate.sh` from master.
+- `generate.sh` runs all versions sequentially in one job.
+- Deploys to Netlify with `--prod`.
+
+### 3. PR preview (`netlify-deploy-preview.yaml`)
+
+Triggered automatically on PRs that change `docs/**`.
+
+- Only builds the current branch's docs content (no multi-version).
+- Uses the simpler `hugo-build-action` (no API reference generation).
+- Deploys to a Netlify preview URL (`preview-{PR}--{site}.netlify.app`).
+
+## Local development
+
+Build and serve docs locally using Docker:
+
+```bash
+cd docs
+docker build -t python-sdk-docs -f Dockerfile ..
+docker run --rm -p 1313:1313 python-sdk-docs
+# Open http://localhost:1313/latest/
+```
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `json_builder.py` | Introspects SDK packages into `data.json` |
+| `python_ref_builder.py` | Generates markdown + HTML from `data.json` |
+| `templates/*.html.j2` | Jinja2 templates (replicate old Hugo shortcodes) |
+| `tests/test_python_ref_builder.py` | Unit tests (`make test-docs-scripts`) |
+| `../script-requirements.txt` | Python dependencies for both scripts |
+| `../../docs/api_spec.toml` | Maps package names to output directories |
+| `../../docs/*_template.md` | Markdown front matter templates (module/class/function) |
+
+## Running tests
+
+```bash
+make test-docs-scripts
+```