ci: run docs versioning commands through uv run#928
Merged
Conversation
The pnpm migration (#855) dropped the uv run wrapper around the docusaurus docs:version/api:version commands. The typedoc-api plugin spawns a bare python to generate the API reference dump, which needs pydoc-markdown from the project venv — without uv run the script fails and the Version docs job (and the dependent Doc release) breaks, leaving the docs site on the old version. This is why the 3.4.0 and 3.4.1 releases never updated the docs.
vdusek
added
adhoc
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #928 +/- ##
==========================================
- Coverage 86.98% 86.94% -0.04%
==========================================
Files 48 48
Lines 2942 2942
==========================================
- Hits 2559 2558 -1
- Misses 383 384 +1
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
vdusek
added a commit
that referenced
this pull request
Jun 3, 2026
Adds the 3.4 docs snapshot that the release pipeline failed to create for v3.4.0 and v3.4.1 — the `Version docs` job was broken until #928, so `versions.json` and the version dropdown on the docs website are still stuck at 3.3. - Replaces the 3.3 snapshot with 3.4 (the workflow keeps one minor per major), updating `versioned_docs`, `versioned_sidebars`, and `versions.json`. - Generated from the `release-v3` branch (v3.4.1) using the exact commands the fixed workflow runs (`uv run pnpm exec docusaurus docs:version 3.4` + `api:version 3.4`), so the API reference documents the released v3 API rather than the v4-dev code on master. Verified: the snapshot still contains the `RemainingTime` timeout literal that was removed on master in #918. Merging this with the `docs:` prefix triggers a docs deploy from master, which updates the version dropdown and the "Version: 3.x" badge on the website.
barjin
pushed a commit
to apify/docusaurus-plugin-typedoc-api
that referenced
this pull request
Jun 3, 2026
## Summary `processPythonDocs` only checks `spawnSync().error`, which is set when the spawn itself fails — a non-zero exit of `generate_ast.py` (e.g. `pydoc-markdown` not importable by the resolved `python`) went completely unnoticed. The plugin then crashed later with a confusing `ENOENT: pydoc-markdown-dump.json`, hiding the real cause. This is exactly what made the broken `Version docs` CI job in apify/apify-sdk-python (failed 3.4.0/3.4.1 doc releases) hard to diagnose — see apify/apify-sdk-python#928 for the workflow-side fix. Now the exit code is checked and the script's stderr is included in the thrown error: ``` [ERROR] Error: The generate_ast.py script failed with exit code 1: ModuleNotFoundError: No module named pydoc_markdown ``` Verified by building the plugin, dropping the compiled output into the SDK website's `node_modules`, and running `docusaurus api:version` with a stub `python` that exits 1.
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
2 participants
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
The
Version docsjob has failed on both the 3.4.0 and 3.4.1 releases, which also skipped the dependentDoc releasejob — the docs site is still stuck on 3.3 (version dropdown andVersion: 3.3badge).Root cause: the pnpm migration (#855) changed the snapshot step from
uv run npx docusaurus ...to plainpnpm exec docusaurus ..., dropping theuv runwrapper. The@apify/docusaurus-plugin-typedoc-apiplugin spawns a barepythonto generate the API reference dump (generate_ast.py), which needspydoc-markdownfrom the project venv. Withoutuv run, the venv is not on PATH, the script fails (the plugin only checks for spawn errors, not the exit code), and the job dies later withENOENT: pydoc-markdown-dump.json— exactly what the logs of runs 26631120750 and 25363849495 show.This restores the
uv runwrapper (consistent with thebuild-docspoe task, which is why doc deploys themselves still worked) and adds a comment explaining why it is needed. Verified locally: the snapshot sequence fails withoutuv runand passes with it.Follow-up (separate from this PR): the fix needs to be cherry-picked to
release-v3,Version docsre-dispatched there with version3.4.1,Release docsre-dispatched, and the snapshot synced back to master.