Make each Python SDK its own independent sphinx docset#18981
Conversation
Replaces the implicit "one shared sphinx docset spanning all packages" model with three independent per-package docsets. Each per-package workflow now produces output that depends only on its own package; a regen of one package no longer affects the rendered HTML of the others. Layout change: - tools/pydocgen/source/pulumi/ — own conf.py + index.rst - tools/pydocgen/source/pulumi_policy/ — own conf.py + index.rst - tools/pydocgen/source/pulumi_esc_sdk/ — own conf.py + index.rst Each conf.py displays the installed package version (via importlib.metadata.version) in the rendered docs' sidebar, so reference pages now indicate which release they correspond to. Falls back to "unknown" if the package isn't installed (e.g. local dev without pipenv). generate_python_docs.sh is simpler: pick the right source/<PACKAGE>/ dir and build directly to static-prebuilt/.../python/<PACKAGE>/. No temp dirs, no fabricated single-package toctree. Install only the target package (and pulumi where Policy needs it for autodoc). Adds a Hugo content stub at content/docs/reference/pkg/python/ that replaces the sphinx-generated unified parent index.html. Hugo runs after the static-prebuilt copy step in build-site.sh, so the new _index.md will override the orphaned sphinx index.html on the next deploy. This is a corollary of issue #18934 (Part 4 follow-up). Fixes a regression where PR #18980's preview site showed only the pulumi package without sibling-package sidebar links — the per-package builds were correctly producing isolated output, but the layout assumed a shared docset. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Docs reviewScoped review of
|
Three new cards under Reference for the ESC SDK across the three languages it ships: TypeScript (Node.js), Python, and Go. Mirrors the "Language SDKs" and "Policy SDKs" sections immediately above. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Your site preview for commit d031e9f is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-18981-d031e9f5.s3-website.us-west-2.amazonaws.com |
The dotnet and python per-language reference pages have _index.md landing pages listing their available SDKs, but nodejs did not, so /docs/reference/pkg/nodejs/ surfaced no ESC SDK link. Mirror the python/_index.md structure with the three Node.js SDKs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hugo's dev server doesn't serve content from static-prebuilt/, so SDK
reference pages 404 in dev mode. This trips up anyone trying to preview
their changes to /docs/reference/pkg/... locally without realizing they
need the build + serve-static combo.
Adds explicit notes to:
* README.md — expands the make serve / make build / make serve-static
entries in the Makefile helpers list to call out the gap.
* BUILD-AND-DEPLOY.md — adds a callout in the Local Development section.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Reference > SDKs section of the left nav is defined in config/_default/menus.yml as a hand-curated list, separate from the content frontmatter menus. It previously had 5 Language SDK entries + 2 Policy SDK entries but no ESC SDK entries — so the ESC SDKs were missing from the navigation even though they appeared in the Reference home page's card layout. Adds three new entries under `reference-sdks`: * TypeScript ESC SDK * Python ESC SDK * Go ESC SDK Also fixes the Go ESC SDK URL on the Reference home page card to match: `https://pkg.go.dev/github.com/pulumi/esc-sdk/sdk/go` is the actual package documentation; the shorter `/sdk` URL pkg.go.dev only renders the module root with "this package is not in the latest version". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Lighthouse Performance ReportCommit: d031e9f | Metric definitions
|
The verbose "TypeScript (Node.js)" label was inherited from the Reference home page card; the left-nav already shows three TypeScript-related SDK entries (Pulumi, Policy, ESC), so just "TypeScript" reads cleaner here. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 participants
Summary
Fixes the regression where PR #18980's preview site showed only
pulumipackage content without sibling-package sidebar links. The per-package builds were correctly producing isolated output, but the layout assumed a shared docset spanning all packages.This PR switches to Option 2 from our discussion: each Python SDK is now its own independent sphinx docset.
What changed
conf.py+index.rst:tools/pydocgen/source/pulumi/tools/pydocgen/source/pulumi_policy/tools/pydocgen/source/pulumi_esc_sdk/conf.pyreads its package's installed version viaimportlib.metadata.version()and setsversion/releaseso the RTD theme renders it in the sidebar.scripts/generate_python_docs.shpicks./source/${PACKAGE}/and builds directly tostatic-prebuilt/docs/reference/pkg/python/${PACKAGE}/. No temp dirs, no fabricated one-package toctree.content/docs/reference/pkg/python/_index.mdrenders the parent/docs/reference/pkg/python/page as a hand-curated list of the three SDKs. Replaces the role of the sphinx-generated unified index. Hugo runs after the static-prebuilt copy inbuild-site.sh, so this Hugo page wins the path collision on next deploy.Trade-offs
pulumi_policyrelease on PyPI no longer blockspulumidocs.pulumi_policyreferencingpulumi.Resourcewill render as a code span rather than a link. In practice these refs are rare and the trade-off is worth the decoupling. If we miss them later, intersphinx is a clean follow-up.Orphaned files
The shared top-level sphinx artifacts (
static-prebuilt/docs/reference/pkg/python/{_static,genindex,search,...}/,objects.inv,searchindex.js, the oldindex.html) become orphans after this PR. They're still referenced by the existingpulumi/index.html,pulumi_policy/index.html,pulumi_esc_sdk/index.htmlon master (which link to../_static/,../genindex/, etc.).As each per-package workflow runs post-merge, the new self-contained per-package output will replace those files. After all three packages have been regenerated, the top-level sphinx assets can be deleted in a follow-up. They're harmless dead weight in the meantime.
Test plan
Pre-merge (already done)
bash -n scripts/generate_python_docs.sh— shell syntax OK.conf.pyfiles parse cleanly as Python (project, version, release fields populate).make lintclean.Post-merge
Visit the new Hugo hub. Browse to https://www.pulumi.com/docs/reference/pkg/python/ (or the preview site) and confirm the page lists the three SDKs as a Hugo-rendered hub, not the old sphinx index.
Regenerate each Python SDK with the new layout. Each workflow now produces a self-contained docset; the resulting PR's diff should rewrite many files in
static-prebuilt/docs/reference/pkg/python/<pkg>/.```bash
gh workflow run pulumi-sdk-python-docs.yml --repo pulumi/docs --ref master -f version=3.238.0
gh workflow run pulumi-policy-sdk-python-docs.yml --repo pulumi/docs --ref master -f version=1.20.0
gh workflow run pulumi-esc-sdk-python-docs.yml --repo pulumi/docs --ref master -f version=0.13.1
```
For each PR, strip
automation/mergelabel and disable auto-merge before reviewing (consistent with our usual test posture):```bash
gh pr edit --remove-label automation/merge --repo pulumi/docs
gh pr merge --disable-auto --repo pulumi/docs
```
Verify each preview site. For each generated PR's preview:
/docs/reference/pkg/python/<pkg>/renders the package's docs.Verify the hub page. After all three packages regenerate, the
/docs/reference/pkg/python/URL should still serve the Hugo hub (Hugo runs second; takes precedence).Rollback
If something is broken,
git revertthis commit. The old per-package builds (with shared parent index) will resume producing output that links to the still-present shared assets.🤖 Generated with Claude Code