fix(docs): always use griffe and method_page_renderer#1436
Merged
hkad98 merged 2 commits intogooddata:masterfrom Mar 19, 2026
Merged
fix(docs): always use griffe and method_page_renderer#1436hkad98 merged 2 commits intogooddata:masterfrom
hkad98 merged 2 commits intogooddata:masterfrom
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. 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. 🚀 New features to boost your workflow:
|
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
d8d69c3 to
cc20711
Compare
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
Mara3l
approved these changes
Mar 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Several fixes for the V2 docs pipeline building old release branches:
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 thejson_builder.pyfallback that causedModuleNotFoundErrorand thepip install -eworkaround from fix(docs): install SDK packages in V2 deploy for legacy builder #1433.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 withoutapi_reffrontmatter, somethod_page_renderer.pyskips them and Hugo needs the templates to render them.Fix duplicate-named module/class pages not being generated.
python_ref_builderused the leaf name as thelinksdict key with anif name not in linksguard that skipped page creation for modules sharing a name (e.g.declarative_modelexists underdata_source,workspace,user, andpermission). Only the first was generated.Fix broken cross-links in module listings and class method tables. Used the global
linksdict to resolve child names, causing e.g.load_from_diskinCatalogDeclarativeDataSourcesto link to workspace's version. Now uses relativehref="child_name/".Re-enable version caching with updated cache key that includes
docs/layouts/shortcodes/**.Note on failing Netlify Deploy Preview
The
Netlify Deploy Previewworkflow failure is expected and not caused by this PR. That workflow (.github/workflows/netlify-deploy-preview.yaml) checks out master'sdocs/layouts/directory (which doesn't have the shortcode templates yet) and only rsyncsdocs/content/en/from the PR branch. Once this PR merges to master, the preview workflow will have the restored shortcode templates and work correctly.