diff --git a/.rat-excludes b/.rat-excludes index 44cf26ac6a3..30b1ef1da9d 100644 --- a/.rat-excludes +++ b/.rat-excludes @@ -43,6 +43,9 @@ _build/* _static/* .buildinfo searchindex.js +# auto-generated by docs/scripts/convert-api-sidebar.mjs from openapi.json +sidebar.js +sidebar.ts # auto generated requirements/* # vendorized diff --git a/docs/DOCS_CLAUDE.md b/docs/DOCS_CLAUDE.md index 1ac49462afe..6aae4a2b21d 100644 --- a/docs/DOCS_CLAUDE.md +++ b/docs/DOCS_CLAUDE.md @@ -31,8 +31,9 @@ You are currently in the `/docs` subdirectory of the Apache Superset repository. ├── superset-frontend/ # React/TypeScript frontend └── docs/ # Documentation site (YOU ARE HERE) ├── docs/ # Main documentation content - ├── developer_portal/ # Developer guides (currently disabled) - ├── components/ # Component playground (currently disabled) + ├── admin_docs/ # Admin-focused guides + ├── developer_docs/ # Developer guides + ├── components/ # Component playground └── docusaurus.config.ts # Site configuration ``` @@ -47,11 +48,13 @@ yarn serve # Serve built site locally # Version Management (USE THESE, NOT docusaurus commands) yarn version:add:docs # Add new docs version -yarn version:add:developer_portal # Add developer portal version +yarn version:add:admin_docs # Add admin docs version +yarn version:add:developer_docs # Add developer docs version yarn version:add:components # Add components version yarn version:remove:docs # Remove docs version -yarn version:remove:developer_portal # Remove developer portal version -yarn version:remove:components # Remove components version +yarn version:remove:admin_docs # Remove admin docs version +yarn version:remove:developer_docs # Remove developer docs version +yarn version:remove:components # Remove components version # Quality Checks yarn typecheck # TypeScript validation @@ -95,15 +98,14 @@ docs/ └── [security guides] ``` -### Developer Portal (`/developer_portal`) - Currently Disabled -When enabled, contains developer-focused content: -- API documentation -- Architecture guides -- CLI tools -- Code examples +### Admin Docs (`/admin_docs`) +Admin-focused content: installation, configuration, security. -### Component Playground (`/components`) - Currently Disabled -When enabled, provides interactive component examples for UI development. +### Developer Docs (`/developer_docs`) +Developer-focused content: API documentation, architecture guides, CLI tools, code examples. + +### Component Playground (`/components`) +Interactive component examples for UI development. ## 📝 Documentation Standards diff --git a/docs/README.md b/docs/README.md index 6f3a6b4902e..3c7f268a288 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/components/versions.json b/docs/components/versions.json deleted file mode 100644 index fe51488c706..00000000000 --- a/docs/components/versions.json +++ /dev/null @@ -1 +0,0 @@ -[] diff --git a/docs/developer_docs/versions.json b/docs/developer_docs/versions.json deleted file mode 100644 index fe51488c706..00000000000 --- a/docs/developer_docs/versions.json +++ /dev/null @@ -1 +0,0 @@ -[] diff --git a/docs/developer_portal_versions.json b/docs/developer_portal_versions.json deleted file mode 100644 index fe51488c706..00000000000 --- a/docs/developer_portal_versions.json +++ /dev/null @@ -1 +0,0 @@ -[] diff --git a/docs/package.json b/docs/package.json index 03e16a17252..66c590edf52 100644 --- a/docs/package.json +++ b/docs/package.json @@ -33,10 +33,12 @@ "version:add": "node scripts/manage-versions.mjs add", "version:remove": "node scripts/manage-versions.mjs remove", "version:add:docs": "node scripts/manage-versions.mjs add docs", - "version:add:developer_portal": "node scripts/manage-versions.mjs add developer_portal", + "version:add:admin_docs": "node scripts/manage-versions.mjs add admin_docs", + "version:add:developer_docs": "node scripts/manage-versions.mjs add developer_docs", "version:add:components": "node scripts/manage-versions.mjs add components", "version:remove:docs": "node scripts/manage-versions.mjs remove docs", - "version:remove:developer_portal": "node scripts/manage-versions.mjs remove developer_portal", + "version:remove:admin_docs": "node scripts/manage-versions.mjs remove admin_docs", + "version:remove:developer_docs": "node scripts/manage-versions.mjs remove developer_docs", "version:remove:components": "node scripts/manage-versions.mjs remove components" }, "dependencies": { diff --git a/docs/scripts/manage-versions.mjs b/docs/scripts/manage-versions.mjs index d96dfc355a9..6a23d6a06a0 100644 --- a/docs/scripts/manage-versions.mjs +++ b/docs/scripts/manage-versions.mjs @@ -32,7 +32,7 @@ const CONFIG_FILE = path.join(__dirname, '..', 'versions-config.json'); // Parse command line arguments const args = process.argv.slice(2); const command = args[0]; // 'add' or 'remove' -const section = args[1]; // 'docs', 'developer_portal', or 'components' +const section = args[1]; // 'docs', 'developer_docs', or 'components' const version = args[2]; // version string like '1.2.0' function loadConfig() { @@ -43,36 +43,59 @@ function saveConfig(config) { fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n'); } -function fixVersionedImports(version) { - const versionedDocsPath = path.join(__dirname, '..', 'versioned_docs', `version-${version}`); +function fixVersionedImports(section, version) { + // Versioned content lands one directory deeper than the source content, + // so any `../../src/` or `../../data/` imports in .md/.mdx files need + // an extra `../` to keep reaching docs/src and docs/data. + const versionedDocsDir = section === 'docs' + ? `versioned_docs/version-${version}` + : `${section}_versioned_docs/version-${version}`; + const versionedDocsPath = path.join(__dirname, '..', versionedDocsDir); - // Files that need import path fixes - const filesToFix = [ - 'contributing/resources.mdx', - 'configuration/country-map-tools.mdx' - ]; + if (!fs.existsSync(versionedDocsPath)) { + return; + } - console.log(` Fixing relative imports in versioned docs...`); + console.log(` Fixing relative imports in ${versionedDocsDir}...`); - filesToFix.forEach(filePath => { - const fullPath = path.join(versionedDocsPath, filePath); - if (fs.existsSync(fullPath)) { - let content = fs.readFileSync(fullPath, 'utf8'); - - // Fix imports that go up two directories to go up three instead - content = content.replace( - /from ['"]\.\.\/\.\.\/src\//g, - "from '../../../src/" - ); - content = content.replace( - /from ['"]\.\.\/\.\.\/data\//g, - "from '../../../data/" - ); - - fs.writeFileSync(fullPath, content); - console.log(` Fixed imports in ${filePath}`); + // Imports whose `../` count exceeds the file's depth within the section + // escape the section root, so they need one extra `../` once the file + // lives one level deeper inside the snapshot dir. Imports that stay + // inside the section are unaffected (the section copies wholesale). + function walk(dir, depth) { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const fullPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + walk(fullPath, depth + 1); + } else if (entry.isFile() && /\.(md|mdx)$/.test(entry.name)) { + const original = fs.readFileSync(fullPath, 'utf8'); + // Track fenced code blocks so we don't rewrite import samples inside + // ```ts / ```js (etc.) blocks that are documentation, not real imports. + let inFence = false; + const updated = original.split('\n').map(line => { + if (/^\s*(```|~~~)/.test(line)) { + inFence = !inFence; + return line; + } + if (inFence) return line; + return line.replace( + /(from\s+['"])((?:\.\.\/)+)/g, + (match, prefix, dots) => { + const upCount = dots.match(/\.\.\//g).length; + return upCount > depth ? `${prefix}../${dots}` : match; + }, + ); + }).join('\n'); + if (updated !== original) { + fs.writeFileSync(fullPath, updated); + const rel = path.relative(versionedDocsPath, fullPath); + console.log(` Fixed imports in ${rel}`); + } + } } - }); + } + + walk(versionedDocsPath, 0); } function addVersion(section, version) { @@ -103,10 +126,8 @@ function addVersion(section, version) { process.exit(1); } - // Fix relative imports in versioned docs (for main docs section only) - if (section === 'docs') { - fixVersionedImports(version); - } + // Fix relative imports in versioned content + fixVersionedImports(section, version); // Update config // Add to onlyIncludeVersions array (after 'current') @@ -215,12 +236,12 @@ Usage: node scripts/manage-versions.js remove
Where: - - section: 'docs', 'developer_portal', or 'components' + - section: 'docs', 'developer_docs', or 'components' - version: version string (e.g., '1.2.0', '2.0.0') Examples: node scripts/manage-versions.js add docs 2.0.0 - node scripts/manage-versions.js add developer_portal 1.3.0 + node scripts/manage-versions.js add developer_docs 1.3.0 node scripts/manage-versions.js remove components 1.0.0 `); } diff --git a/docs/src/theme/DocVersionBadge/index.js b/docs/src/theme/DocVersionBadge/index.js index a76ced7e254..c5791fb75a5 100644 --- a/docs/src/theme/DocVersionBadge/index.js +++ b/docs/src/theme/DocVersionBadge/index.js @@ -40,8 +40,8 @@ export default function DocVersionBadge() { const isVersioned = [ 'default', // main docs 'components', - 'tutorials', - 'developer_portal', + 'admin_docs', + 'developer_docs', ].includes(pluginId); const { preferredVersion } = useDocsPreferredVersion(pluginId); diff --git a/docs/src/theme/DocVersionBanner/index.js b/docs/src/theme/DocVersionBanner/index.js index 3704128bedc..2a0e91a2dde 100644 --- a/docs/src/theme/DocVersionBanner/index.js +++ b/docs/src/theme/DocVersionBanner/index.js @@ -37,9 +37,8 @@ export default function DocVersionBannerWrapper(props) { const pluginId = activePlugin?.pluginId; const [versionedPath, setVersionedPath] = useState(''); - // Only show version selector for tutorials - // Main docs, components, and developer_portal use the DocVersionBadge component instead - const isVersioned = pluginId && ['tutorials'].includes(pluginId); + // Versioned sections use the DocVersionBadge component instead of this banner + const isVersioned = false; const { preferredVersion } = useDocsPreferredVersion(pluginId); const versions = useVersions(pluginId); diff --git a/docs/tutorials_versions.json b/docs/tutorials_versions.json deleted file mode 100644 index 5e1abcd8a61..00000000000 --- a/docs/tutorials_versions.json +++ /dev/null @@ -1,3 +0,0 @@ -[ - "1.0.0" -]