diff --git a/.github/workflows/netlify-deploy-v2.yaml b/.github/workflows/netlify-deploy-v2.yaml index cb9422fc8..a1886d5e1 100644 --- a/.github/workflows/netlify-deploy-v2.yaml +++ b/.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-${{ hashFiles('scripts/docs/*.py', 'scripts/docs/templates/**', 'docs/*_template.md') }}-${{ matrix.version.section }}-${{ steps.sha.outputs.sha }} + key: version-docs-${{ hashFiles('scripts/docs/*.py', 'scripts/docs/templates/**', 'docs/*_template.md', 'docs/layouts/shortcodes/**') }}-${{ matrix.version.section }}-${{ steps.sha.outputs.sha }} - name: Checkout if: steps.cache.outputs.cache-hit != 'true' uses: actions/checkout@v4 @@ -67,9 +67,6 @@ jobs: run: | python -m pip install --upgrade pip pip install -r scripts/script-requirements.txt - # json_builder.py (legacy fallback for branches without griffe_builder.py) - # imports gooddata_sdk and gooddata_pandas at runtime, so they must be installed. - pip install -e gooddata-api-client/ -e packages/gooddata-sdk/ -e packages/gooddata-pandas/ - name: Generate version docs if: steps.cache.outputs.cache-hit != 'true' run: bash scripts/generate-single-version.sh "origin/${{ matrix.version.branch }}" "${{ matrix.version.section }}" diff --git a/docs/layouts/shortcodes/parameter.html b/docs/layouts/shortcodes/parameter.html new file mode 100644 index 000000000..8912e9d21 --- /dev/null +++ b/docs/layouts/shortcodes/parameter.html @@ -0,0 +1,5 @@ + +{{ with .Get "p_name" }}{{ . | safeHTML }}{{ end }} +{{ with .Get "p_type" }}{{ . | safeHTML }}{{ end }} +{{.Inner | safeHTML}} + diff --git a/docs/layouts/shortcodes/parameters-block.html b/docs/layouts/shortcodes/parameters-block.html new file mode 100644 index 000000000..c3e332a48 --- /dev/null +++ b/docs/layouts/shortcodes/parameters-block.html @@ -0,0 +1,20 @@ +{{ $partitle := .Get "title"}} +

{{$partitle}}

+{{ with .Get `None`}} +None +{{else}} + + + +{{ if eq $partitle "Parameters"}} + +{{end}} + + + + + +{{.Inner}} + +
nametypedescription
+{{end}} diff --git a/scripts/docs/python_ref_builder.py b/scripts/docs/python_ref_builder.py index 3e383aceb..f90fc6d65 100644 --- a/scripts/docs/python_ref_builder.py +++ b/scripts/docs/python_ref_builder.py @@ -242,12 +242,14 @@ def render_class_html(class_data: dict, parent_name: str, import_path: str, reso continue fds = fdata.get("docstring_parsed") desc = resolver.all_links(fds.get("short_description", "")) if fds else "" + # Link to the method's own child page (relative), not the global links dict + local_link = f'{fname}' if fdata.get("is_property"): - properties.append({"name_link": resolver.type_link(fname), "description": desc}) + properties.append({"name_link": local_link, "description": desc}) else: methods.append( { - "name_link": resolver.type_link(fname), + "name_link": local_link, "signature": _function_signature(fdata), "description": desc, } @@ -263,7 +265,9 @@ def render_module_html(module_data: dict, resolver: LinkResolver) -> str: for obj_name, obj_data in module_data.items(): if obj_name == "kind" or not isinstance(obj_data, dict): continue - entries.append({"kind": obj_data.get("kind", ""), "name_link": resolver.type_link(obj_name)}) + # Link to the child page (relative), not the global links dict + local_link = f'{obj_name}' + entries.append({"kind": obj_data.get("kind", ""), "name_link": local_link}) return _MODULE_TPL.render(entries=entries) @@ -333,34 +337,34 @@ def _pass1(data_root: dict, dir_root: Path, api_ref_root: str, module_import_pat obj_module_import_path = obj_module_import_path.replace(".functions", "") if kind == "module": + (dir_root / name).mkdir(exist_ok=True) if name not in links: - (dir_root / name).mkdir(exist_ok=True) links[name] = {"path": f"{api_ref_root}/{name}".lower(), "kind": "function"} - pages.append( - _PageSpec( - kind="module", - name=name, - parent_name="", - import_path=obj_module_import_path, - file_path=dir_root / name / "_index.md", - data=obj, - ) + pages.append( + _PageSpec( + kind="module", + name=name, + parent_name="", + import_path=obj_module_import_path, + file_path=dir_root / name / "_index.md", + data=obj, ) + ) elif kind == "class": + (dir_root / name).mkdir(exist_ok=True) if name not in links: - (dir_root / name).mkdir(exist_ok=True) links[name] = {"path": f"{api_ref_root}/{name}".lower(), "kind": "class"} - pages.append( - _PageSpec( - kind="class", - name=name, - parent_name=module_import_path.split(".")[-1], - import_path=obj_module_import_path, - file_path=dir_root / name / "_index.md", - data=obj, - ) + pages.append( + _PageSpec( + kind="class", + name=name, + parent_name=module_import_path.split(".")[-1], + import_path=obj_module_import_path, + file_path=dir_root / name / "_index.md", + data=obj, ) + ) elif name == "functions": for func_name in obj: diff --git a/scripts/generate-single-version.sh b/scripts/generate-single-version.sh index 3d86130d6..828695d61 100755 --- a/scripts/generate-single-version.sh +++ b/scripts/generate-single-version.sh @@ -54,31 +54,27 @@ if git cat-file -e "$GRIFFE_GEN_FILE" 2>/dev/null || git cat-file -e "$LEGACY_GE rm -f api_spec.toml fi - # Generate API introspection data — prefer griffe (static analysis, no imports needed) - if git cat-file -e "$GRIFFE_GEN_FILE" 2>/dev/null; then - echo "Using griffe_builder.py (static analysis)" - python3 ../scripts/docs/griffe_builder.py \ - --search-path ../packages/gooddata-sdk/src \ - --search-path ../packages/gooddata-pandas/src \ - --output data.json \ - gooddata_sdk gooddata_pandas - else - echo "Falling back to json_builder.py (runtime introspection)" - python3 ../scripts/docs/json_builder.py - fi + # Generate API introspection data using griffe (static analysis, no imports needed). + # Always use the current branch's griffe_builder.py — it works on any branch's + # source code via --search-path and doesn't require the SDK packages to be installed. + python3 ../scripts/docs/griffe_builder.py \ + --search-path ../packages/gooddata-sdk/src \ + --search-path ../packages/gooddata-pandas/src \ + --output data.json \ + gooddata_sdk gooddata_pandas # Generate API reference markdown files and export links for method page renderer python3 ../scripts/docs/python_ref_builder.py api_spec.toml \ data.json "$section" "$content_dir" \ --export-links links.json - # Pre-render method pages with api_ref directives - if git cat-file -e "$branch:scripts/docs/method_page_renderer.py" 2>/dev/null; then - echo "Pre-rendering method pages for section $section..." - python3 ../scripts/docs/method_page_renderer.py \ - data.json "$content_dir/$section" \ - --links-json links.json - fi + # Pre-render method pages with api_ref directives. + # Always use the current branch's renderer — old branches have Hugo shortcodes + # (parameters-block, parameter) whose templates were removed. + echo "Pre-rendering method pages for section $section..." + python3 ../scripts/docs/method_page_renderer.py \ + data.json "$content_dir/$section" \ + --links-json links.json # Clean up intermediate files (no longer needed after pre-rendering) rm -f data.json links.json diff --git a/scripts/generate.sh b/scripts/generate.sh index 3a208b4a8..5796daf0c 100755 --- a/scripts/generate.sh +++ b/scripts/generate.sh @@ -103,24 +103,21 @@ for branch in "${branches_to_process[@]}" ; do echo "removing the API_spec" rm -rf api_spec.toml fi - # Prefer griffe (static analysis, no imports needed) - if git cat-file -e "$GRIFFE_GEN_FILE" 2>/dev/null; then - python3 ../scripts/docs/griffe_builder.py \ - --search-path ../packages/gooddata-sdk/src \ - --search-path ../packages/gooddata-pandas/src \ - --output data.json \ - gooddata_sdk gooddata_pandas - else - python3 ../scripts/docs/json_builder.py - fi + # Always use griffe (static analysis, no imports needed). + # Works on any branch's source code via --search-path. + python3 ../scripts/docs/griffe_builder.py \ + --search-path ../packages/gooddata-sdk/src \ + --search-path ../packages/gooddata-pandas/src \ + --output data.json \ + gooddata_sdk gooddata_pandas python3 ../scripts/docs/python_ref_builder.py api_spec.toml data.json "$target_section" versioned_docs \ --export-links links.json - # Pre-render method pages with api_ref directives - if git cat-file -e "$branch:scripts/docs/method_page_renderer.py" 2>/dev/null; then - python3 ../scripts/docs/method_page_renderer.py \ - data.json "versioned_docs/$target_section" \ - --links-json links.json - fi + # Pre-render method pages with api_ref directives. + # Always use the current branch's renderer — old branches have Hugo shortcodes + # (parameters-block, parameter) whose templates were removed. + python3 ../scripts/docs/method_page_renderer.py \ + data.json "versioned_docs/$target_section" \ + --links-json links.json rm -f data.json links.json fi fi