Skip to content

fix(docs): always use griffe and method_page_renderer#1436

Merged
hkad98 merged 2 commits intogooddata:masterfrom
hkad98:jkd/fix-method-page-renderer
Mar 19, 2026
Merged

fix(docs): always use griffe and method_page_renderer#1436
hkad98 merged 2 commits intogooddata:masterfrom
hkad98:jkd/fix-method-page-renderer

Conversation

@hkad98
Copy link
Copy Markdown
Contributor

@hkad98 hkad98 commented Mar 16, 2026

Summary

Several fixes for the V2 docs pipeline building old release branches:

  1. Always use griffe_builder.py and method_page_renderer.py from the current branch instead of checking if they exist on the target branch. The scripts were always executed from the current branch anyway, and griffe does static analysis via --search-path (no imports needed). This removes the json_builder.py fallback that caused ModuleNotFoundError and the pip install -e workaround from fix(docs): install SDK packages in V2 deploy for legacy builder #1433.

  2. Restore Hugo shortcode templates (parameters-block, parameter) that were deleted in the griffe pipeline commit. Old release branches have hand-written method pages using these shortcodes without api_ref frontmatter, so method_page_renderer.py skips them and Hugo needs the templates to render them.

  3. Fix duplicate-named module/class pages not being generated. python_ref_builder used the leaf name as the links dict key with an if name not in links guard that skipped page creation for modules sharing a name (e.g. declarative_model exists under data_source, workspace, user, and permission). Only the first was generated.

  4. Fix broken cross-links in module listings and class method tables. Used the global links dict to resolve child names, causing e.g. load_from_disk in CatalogDeclarativeDataSources to link to workspace's version. Now uses relative href="child_name/".

  5. Re-enable version caching with updated cache key that includes docs/layouts/shortcodes/**.

Note on failing Netlify Deploy Preview

The Netlify Deploy Preview workflow failure is expected and not caused by this PR. That workflow (.github/workflows/netlify-deploy-preview.yaml) checks out master's docs/layouts/ directory (which doesn't have the shortcode templates yet) and only rsyncs docs/content/en/ from the PR branch. Once this PR merges to master, the preview workflow will have the restored shortcode templates and work correctly.

@codecov
Copy link
Copy Markdown

codecov bot commented Mar 17, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.27%. Comparing base (e650ab3) to head (63594e9).
⚠️ Report is 11 commits behind head on master.

Additional details and impacted files
@@            Coverage Diff             @@
##           master    #1436      +/-   ##
==========================================
- Coverage   77.36%   77.27%   -0.09%     
==========================================
  Files         228      227       -1     
  Lines       14775    14687      -88     
==========================================
- Hits        11430    11350      -80     
+ Misses       3345     3337       -8     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Several issues with the V2 docs pipeline building old release branches:

1. Always use griffe_builder.py and method_page_renderer.py from the
   current branch instead of checking if they exist on the target branch.
   The scripts were always executed from the current branch anyway, and
   griffe does static analysis via --search-path (no imports needed).
   This removes the json_builder.py fallback that caused
   ModuleNotFoundError and the pip install -e workaround.

2. Restore Hugo shortcode templates (parameters-block, parameter) that
   were deleted in the griffe pipeline commit. Old release branches have
   hand-written method pages using these shortcodes without api_ref
   frontmatter, so method_page_renderer skips them and Hugo needs the
   templates to render them.

3. Fix python_ref_builder generating only one page for modules/classes
   sharing a leaf name (e.g. declarative_model under data_source,
   workspace, user, permission). The "if name not in links" guard
   prevented page creation for all but the first. Now all modules and
   classes always get their pages while the links dict keeps first-wins
   for type-annotation resolution.

4. Use relative links (href="child_name/") for module child listings
   and class method/property tables instead of the global links dict.
   This fixes cross-links where e.g. load_from_disk in
   CatalogDeclarativeDataSources pointed to workspace's version.

5. Temporarily disable version caching while stabilizing the pipeline.

JIRA: trivial
risk: nonprod
@hkad98 hkad98 force-pushed the jkd/fix-method-page-renderer branch from d8d69c3 to cc20711 Compare March 17, 2026 13:17
Re-enable the version docs cache with an updated key that includes
docs/layouts/shortcodes/** so shortcode template changes bust the cache.

JIRA: trivial
risk: nonprod
@hkad98 hkad98 merged commit 2e8d7d7 into gooddata:master Mar 19, 2026
11 of 13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants