mirror of
https://github.com/apache/superset.git
synced 2026-05-29 11:45:16 +00:00
chore(docs): clean up version-cutting tooling and finish developer_portal rename
Tooling-only prep for the upcoming docs version cut. Snapshots will land in a follow-up PR. - Finish the developer_portal -> developer_docs rename: update package.json scripts, manage-versions.mjs usage strings, DocVersionBadge plugin id list (replaces bogus 'tutorials' and 'developer_portal' ids with the real 'default', 'components', 'admin_docs', 'developer_docs'), DocVersionBanner dead branch, DOCS_CLAUDE.md, README.md - Add admin_docs version add/remove scripts (which previously didn't exist) - Generalize fixVersionedImports in manage-versions.mjs to walk every section's snapshot dir with a depth-aware regex, and skip fenced code blocks; replaces the previous hard-coded two-file list - Remove orphan files: developer_portal_versions.json, tutorials_versions.json (no such plugin), and the empty docs/components/versions.json and docs/developer_docs/versions.json that were accidentally tracked inside content directories - Exclude auto-generated sidebar.js and sidebar.ts from the ASF license check (these are produced by docs/scripts/convert-api-sidebar.mjs from the OpenAPI spec, and a future version cut would otherwise commit them)
This commit is contained in:
@@ -45,10 +45,13 @@ To create a new version for any section, use the Docusaurus version command with
|
||||
# Main Documentation
|
||||
yarn version:add:docs 1.2.0
|
||||
|
||||
# Developer Portal
|
||||
yarn version:add:developer_portal 1.2.0
|
||||
# Admin Docs
|
||||
yarn version:add:admin_docs 1.2.0
|
||||
|
||||
# Component Playground (when enabled)
|
||||
# Developer Docs
|
||||
yarn version:add:developer_docs 1.2.0
|
||||
|
||||
# Component Playground
|
||||
yarn version:add:components 1.2.0
|
||||
```
|
||||
|
||||
@@ -91,8 +94,11 @@ If creating versions manually, you'll need to:
|
||||
# Main Documentation
|
||||
yarn version:remove:docs 1.0.0
|
||||
|
||||
# Developer Portal
|
||||
yarn version:remove:developer_portal 1.0.0
|
||||
# Admin Docs
|
||||
yarn version:remove:admin_docs 1.0.0
|
||||
|
||||
# Developer Docs
|
||||
yarn version:remove:developer_docs 1.0.0
|
||||
|
||||
# Component Playground
|
||||
yarn version:remove:components 1.0.0
|
||||
@@ -103,17 +109,20 @@ To manually remove a version:
|
||||
|
||||
1. **Delete the version folder** from the appropriate location:
|
||||
- Main docs: `versioned_docs/version-X.X.X/` (no prefix for main)
|
||||
- Developer Portal: `developer_portal_versioned_docs/version-X.X.X/`
|
||||
- Admin Docs: `admin_docs_versioned_docs/version-X.X.X/`
|
||||
- Developer Docs: `developer_docs_versioned_docs/version-X.X.X/`
|
||||
- Components: `components_versioned_docs/version-X.X.X/`
|
||||
|
||||
2. **Delete the version metadata file**:
|
||||
- Main docs: `versioned_sidebars/version-X.X.X-sidebars.json` (no prefix)
|
||||
- Developer Portal: `developer_portal_versioned_sidebars/version-X.X.X-sidebars.json`
|
||||
- Admin Docs: `admin_docs_versioned_sidebars/version-X.X.X-sidebars.json`
|
||||
- Developer Docs: `developer_docs_versioned_sidebars/version-X.X.X-sidebars.json`
|
||||
- Components: `components_versioned_sidebars/version-X.X.X-sidebars.json`
|
||||
|
||||
3. **Update the versions list file**:
|
||||
- Main docs: `versions.json`
|
||||
- Developer Portal: `developer_portal_versions.json`
|
||||
- Admin Docs: `admin_docs_versions.json`
|
||||
- Developer Docs: `developer_docs_versions.json`
|
||||
- Components: `components_versions.json`
|
||||
|
||||
4. **Update configuration**:
|
||||
@@ -145,12 +154,12 @@ docs: {
|
||||
}
|
||||
```
|
||||
|
||||
#### Developer Portal & Components (custom plugins)
|
||||
#### Developer Docs & Components (custom plugins)
|
||||
```typescript
|
||||
{
|
||||
id: 'developer_portal',
|
||||
path: 'developer_portal',
|
||||
routeBasePath: 'developer_portal',
|
||||
id: 'developer_docs',
|
||||
path: 'developer_docs',
|
||||
routeBasePath: 'developer-docs',
|
||||
includeCurrentVersion: true,
|
||||
lastVersion: '1.1.0', // Default version
|
||||
onlyIncludeVersions: ['current', '1.1.0', '1.0.0'],
|
||||
@@ -194,7 +203,7 @@ For other issues:
|
||||
|
||||
#### Broken Links in Versioned Documentation
|
||||
When creating a new version, links in the documentation are preserved as-is. Common issues:
|
||||
- **Cross-section links**: Links between sections (e.g., from developer_portal to docs) need to be version-aware
|
||||
- **Cross-section links**: Links between sections (e.g., from developer_docs to docs) need to be version-aware
|
||||
- **Absolute vs relative paths**: Use relative paths within the same section
|
||||
- **Version-specific URLs**: Update hardcoded URLs to use version variables
|
||||
|
||||
|
||||
Reference in New Issue
Block a user