rusackas opened a new pull request, #40171:
URL: https://github.com/apache/superset/pull/40171
### SUMMARY
Replies in part to a review comment on #40126 asking to clean up the docs
versioning layout.
Of the four versioned docs sections, three (`admin_docs`, `developer_docs`,
`components`) use the standard Docusaurus `<plugin_id>_versioned_docs` /
`<plugin_id>_versioned_sidebars` / `<plugin_id>_versions.json` naming on disk.
The fourth — the user-docs section — was wired through `preset-classic`'s
bundled docs slot, which uses the special `default` plugin id that gets **no
prefix** (`versioned_docs/`, `versioned_sidebars/`, `versions.json`). That's a
Docusaurus quirk, but the result is an inconsistent top-level layout and a
confusingly-bare `versioned_docs` that looks like a global rather than a
per-section dir.
This PR configures user-docs as an explicit `plugin-content-docs` instance
with `id: 'user_docs'` so all four sections produce parallel-named files at the
docs/ root.
### What's in scope vs. what isn't
| Reviewer ask | Status |
|---|---|
| All sections in one `6.1.0/` folder | ❌ Not possible — Docusaurus's
plugin-content-docs is per-plugin by design |
| Each section in its own folder (content + sidebars together) | ❌ Not
possible — `VERSIONED_DOCS_DIR` and `VERSIONED_SIDEBARS_DIR` are hard-coded
constants in Docusaurus |
| Make the bare `versioned_docs/` consistent with the other sections' naming
| ✅ This PR |
### Changes
- **`docusaurus.config.ts`**: add `user_docs` to `dynamicPlugins`; set
`docs: false` on preset-classic
- **`versions-config.json`**: rename `docs` key → `user_docs`
- **File renames** (preserves git history via `git mv`):
- `versioned_docs/` → `user_docs_versioned_docs/`
- `versioned_sidebars/` → `user_docs_versioned_sidebars/`
- `versions.json` → `user_docs_versions.json`
- **`src/theme/DocVersionBadge/index.js`**: update `PLUGIN_ID_TO_BASE_PATH`
(`default` → `user_docs`) and refresh the comment
- **`scripts/manage-versions.mjs`**: drop every `section === 'docs'` special
case (the `user_docs` section's source dir is still `docs/` since we didn't
rename the content folder, but everything else is now uniform with the other
three sections — net code reduction)
- **`package.json`**: rename `version:add:docs` → `version:add:user_docs`
and `version:remove:docs` → `version:remove:user_docs` script aliases
- **`README.md`, `DOCS_CLAUDE.md`**: update examples and naming notes
### URL impact
**None.** The user-docs URL prefix is governed by `routeBasePath:
'user-docs'` (unchanged), not by the plugin id. The existing `6.0.0` versioned
URL `/user-docs/6.0.0/...` continues to resolve — verified via local `yarn
build`. All build output paths under `build/user-docs/...` are identical to
before.
### Why this matters for #40126
When the next 6.1.0 cut runs (planned re-cut on top of this), the snapshot
will land at `user_docs_versioned_docs/version-6.1.0/` instead of the bare
`versioned_docs/version-6.1.0/`, and the top-level `docs/` directory will list
its versioning artifacts in four parallel sets — much easier to scan during
review.
### CLI breaking change
`yarn version:add:docs` → `yarn version:add:user_docs` (and same for
`:remove`). This is internal docs tooling; the new name matches the on-disk
naming. No external callers I'm aware of.
### BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF
N/A.
### TESTING INSTRUCTIONS
```bash
cd docs
yarn install
yarn build
```
Verify:
1. `yarn build` completes (only pre-existing
`/community#superset-community-calendar` anchor warnings — tracked separately).
2. `/user-docs/` and `/user-docs/6.0.0/...` URLs both render correctly via
`yarn serve`.
3. Top-level `docs/` directory now has parallel-named `*_versioned_docs/` /
`*_versioned_sidebars/` / `*_versions.json` for all four sections (no more bare
`versioned_*` outliers).
4. `node scripts/manage-versions.mjs add user_docs <future-version>` runs
end-to-end (writes to `user_docs_versioned_docs/`,
`user_docs_versioned_sidebars/`, `user_docs_versions.json`).
### ADDITIONAL INFORMATION
- [ ] Has associated issue:
- [ ] Required feature flags:
- [ ] Changes UI
- [ ] Includes DB Migration (follow approval process in
[SIP-59](https://github.com/apache/superset/issues/13351))
- [ ] Migration is atomic, supports rollback & is backwards-compatible
- [ ] Confirm DB migration upgrade and downgrade tested
- [ ] Runtime estimates and downtime expectations provided
- [ ] Introduces new feature or API
- [ ] Removes existing feature or API
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
