Merge pull request #1391 from hkad98/jkd/docs-prerender-api-ref

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

Author: hkad98

.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