docs: cut 6.1.0 versions for user_docs, admin_docs, developer_docs, components#40126
Conversation
|
Bito Automatic Review Skipped - Large PR |
✅ Deploy Preview for superset-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #40126 +/- ##
=======================================
Coverage 64.15% 64.16%
=======================================
Files 2591 2591
Lines 138162 138162
Branches 32048 32048
=======================================
+ Hits 88642 88649 +7
+ Misses 47991 47984 -7
Partials 1529 1529
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:
|
rusackas
requested review from
michael-s-molina,
sadpandajoe,
sfirke and
villebro
|
@rusackas Isn't possible to have a 6.1.0 folder with the remaining structures underneath instead of multiple folders with a 6.1 suffix? |
Well... I can tidy it up, I think. The three sections (user/admin/dev) are versioned independently, since that's what we decided to do, and the versioning might get MORE hairy if we start considering package/extension/sdk versioning. That said, I see two fixes I wanna make:
|
|
@michael-s-molina it SEEMS that the two-folder thing (sidebars and content) is hard-coded into Docusaurus, so we can't combine those unless we wanna fork Docusaurus (no thanks!) That said, I'll update versioned_docs to user_docs on a new PR, then adjust this one when it merges. Of course, we CAN revisit the convo of NOT versioning the sections of the site independently at all... we were steering toward flexibility, but that also means complexity. |
|
I approved #40171 - are you going to merge that into here, or close this in favor of a new PR that includes that one? |
…omponents Snapshots all four versioned Docusaurus sections at v6.1.0, cut from master after the version-cutting tooling (#39837), broken-internal- links fix (#40102), and user_docs rename (#40171) all landed. With the rename in place, all four sections now produce parallel-named files at the docs/ root (no more bare `versioned_docs/` outlier). Versioning behavior: lastVersion stays at current for every section, so the canonical URLs (/user-docs/..., /admin-docs/..., /developer-docs/..., /components/...) continue to render content from master. The current version is consistently labeled "Next" with an unreleased banner, and 6.1.0 is a historical pin accessible only via its explicit version segment. Component playground: previously disabled: true in versions-config.json, now enabled and versioned. Snapshot includes: - All MDX content for the four sections. - Auto-gen captured fresh: 74 database pages (engine spec metadata), ~1,800 API reference files (openapi.json), 59 component pages (Storybook stories). - Data imports frozen at cut time into snapshot-local _versioned_data/ dirs: user_docs_versioned_docs/version-6.1.0/_versioned_data/src/data/databases.json (canonical 80-database diagnostics from master, preserved by the generator's input-hash cache) admin_docs_versioned_docs/version-6.1.0/_versioned_data/data/countries.json admin_docs_versioned_docs/version-6.1.0/_versioned_data/static/feature-flags.json developer_docs_versioned_docs/version-6.1.0/_versioned_data/static/data/components.json - Import paths in deeply-nested files rewritten so they still resolve from one directory deeper inside the snapshot. - developer_docs/extensions/overview.md snapshot has the FIXED ./mcp.md form (from #40102), so the SPA-nav 404 isn't baked into the 6.1.0 version. Verified via full yarn build: exit 0, no broken links surfaced by onBrokenLinks: throw.
rusackas
force-pushed
the
chore/docs-cut-6.1.0
branch
from
4266d36 to
4ee42fe
Compare
rusackas
changed the title
|
@sfirke that one just changed the build stuff... now that it's merged (thanks!) this has the docs cut re-built with the new directory naming. |
|
@sfirke @villebro @sadpandajoe this cut should finally be good to go, so we can call it done! |
5 participants
SUMMARY
Cuts a
6.1.0snapshot for all four versioned Docusaurus sections (user_docs,admin_docs,developer_docs,components).Cut from a clean master after the prerequisite work landed:
onBrokenLinks: throw+ fixes for the bare-relative MDX link bug (which would have baked the SPA-nav broken-flow into the 6.1.0 snapshot otherwise)user_docsso all four sections produce parallel-named files at the docs/ rootWith #40171 in place, the snapshot lands at
user_docs_versioned_docs/version-6.1.0/alongside the other three sections instead of the bareversioned_docs/version-6.1.0/outlier — addresses the consistency concern raised on the previous version of this PR.Versioning behavior:
lastVersionstays atcurrentfor every section, so the canonical URLs (/user-docs/...,/admin-docs/...,/developer-docs/...,/components/...) continue to render content from master. Thecurrentversion is consistently labeled "Next" with anunreleasedbanner across all four sections, and6.1.0is a historical pin accessible only via its explicit version segment.Component playground: previously
disabled: trueinversions-config.json, now enabled and versioned. The plugin block indocusaurus.config.tswas already gated only by thedisabledflag, so no other code changes were needed to bring it back online.What's in the snapshot:
superset/db_engine_specs/metadata), ~1,800 API reference files (fromstatic/resources/openapi.jsonviagen-api-docs), 59 component pages (from Storybook stories)._versioned_data/dirs:user_docs_versioned_docs/version-6.1.0/_versioned_data/src/data/databases.json— canonical 80-database diagnostics from master (preserved by the generator's input-hash cache, not regenerated to a local-Flask-env fallback).admin_docs_versioned_docs/version-6.1.0/_versioned_data/data/countries.json— supported-countries list for the Country Map Tools page.admin_docs_versioned_docs/version-6.1.0/_versioned_data/static/feature-flags.json— feature flag tables.developer_docs_versioned_docs/version-6.1.0/_versioned_data/static/data/components.json— component playground index metadata.../../../src/...etc.) so they still resolve correctly from one directory deeper inside the snapshot.developer_docs/extensions/overview.mdsnapshot has the FIXED./mcp.mdform (from fix(docs): tighten onBrokenLinks to throw and fix surfaced broken links #40102), so the SPA-nav 404 isn't baked into the 6.1.0 version.BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF
N/A (versioning change; surfaces existing content under new URL paths).
TESTING INSTRUCTIONS
cd docs yarn install yarn build yarn serveVerify:
/user-docs/...,/admin-docs/...,/developer-docs/...,/components/...) and includes bothNextand6.1.0.currentcontent with the "unreleased" banner, matching the latest source./6.1.0to any section URL renders the historical snapshot with no banner.country-map-tools.mdx(admin_docs/6.1.0) renders all 201 countries from a frozen JSON.feature-flags.mdx(admin_docs/6.1.0) renders the feature-flag tables from a frozen JSON.databases/index.mdx(user_docs/6.1.0) renders the 80-database list from a frozendatabases.json./developer-docs/extensions/overview/(with trailing slash), the "Next Steps" bullets click through correctly to/developer-docs/extensions/X(not/developer-docs/extensions/overview/X).yarn buildalready validated locally — passes withonBrokenLinks: throw. Only warnings are pre-existing anchor warnings on/community#superset-community-calendar(unrelated; tracked separately).ADDITIONAL INFORMATION