docs: bifurcate documentation into user and admin sections (#38196)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Evan Rusackas
2026-02-26 16:29:08 -05:00
committed by GitHub
parent 8a053bbe07
commit 6589ee48f9
171 changed files with 10899 additions and 2866 deletions

View File

@@ -64,27 +64,55 @@ if (!versionsConfig.components.disabled) {
]);
}
// Add developer_portal plugin if not disabled
if (!versionsConfig.developer_portal.disabled) {
// Add admin_docs plugin if not disabled
if (!versionsConfig.admin_docs.disabled) {
dynamicPlugins.push([
'@docusaurus/plugin-content-docs',
{
id: 'developer_portal',
path: 'developer_portal',
routeBasePath: 'developer_portal',
sidebarPath: require.resolve('./sidebarTutorials.js'),
id: 'admin_docs',
path: 'admin_docs',
routeBasePath: 'admin-docs',
sidebarPath: require.resolve('./sidebarAdminDocs.js'),
editUrl:
'https://github.com/apache/superset/edit/master/docs/developer_portal',
'https://github.com/apache/superset/edit/master/docs/admin_docs',
remarkPlugins: [remarkImportPartial, remarkLocalizeBadges, remarkTechArticleSchema],
admonitions: {
keywords: ['note', 'tip', 'info', 'warning', 'danger', 'resources'],
extendDefaults: true,
},
docItemComponent: '@theme/DocItem',
includeCurrentVersion: versionsConfig.developer_portal.includeCurrentVersion,
lastVersion: versionsConfig.developer_portal.lastVersion,
onlyIncludeVersions: versionsConfig.developer_portal.onlyIncludeVersions,
versions: versionsConfig.developer_portal.versions,
includeCurrentVersion: versionsConfig.admin_docs.includeCurrentVersion,
lastVersion: versionsConfig.admin_docs.lastVersion,
onlyIncludeVersions: versionsConfig.admin_docs.onlyIncludeVersions,
versions: versionsConfig.admin_docs.versions,
disableVersioning: false,
showLastUpdateAuthor: true,
showLastUpdateTime: true,
},
]);
}
// Add developer_docs plugin if not disabled
if (!versionsConfig.developer_docs.disabled) {
dynamicPlugins.push([
'@docusaurus/plugin-content-docs',
{
id: 'developer_docs',
path: 'developer_docs',
routeBasePath: 'developer-docs',
sidebarPath: require.resolve('./sidebarTutorials.js'),
editUrl:
'https://github.com/apache/superset/edit/master/docs/developer_docs',
remarkPlugins: [remarkImportPartial, remarkLocalizeBadges, remarkTechArticleSchema],
admonitions: {
keywords: ['note', 'tip', 'info', 'warning', 'danger', 'resources'],
extendDefaults: true,
},
docItemComponent: '@theme/ApiItem', // Required for OpenAPI docs
includeCurrentVersion: versionsConfig.developer_docs.includeCurrentVersion,
lastVersion: versionsConfig.developer_docs.lastVersion,
onlyIncludeVersions: versionsConfig.developer_docs.onlyIncludeVersions,
versions: versionsConfig.developer_docs.versions,
disableVersioning: false,
showLastUpdateAuthor: true,
showLastUpdateTime: true,
@@ -121,45 +149,79 @@ if (!versionsConfig.components.disabled) {
});
}
// Add Developer Portal navbar item if not hidden from nav
if (!versionsConfig.developer_portal.disabled && !versionsConfig.developer_portal.hideFromNav) {
// Add Admin Docs navbar item if not disabled
if (!versionsConfig.admin_docs.disabled) {
dynamicNavbarItems.push({
label: 'Developer Portal',
label: 'Admins',
to: '/admin-docs/',
position: 'left',
activeBaseRegex: '^/admin-docs/',
items: [
{
type: 'doc',
docsPluginId: 'developer_portal',
docId: 'index',
label: 'Overview',
to: '/admin-docs/',
activeBaseRegex: '^/admin-docs/$',
},
{
label: 'Installation',
to: '/admin-docs/installation/installation-methods',
activeBaseRegex: '^/admin-docs/installation/',
},
{
label: 'Configuration',
to: '/admin-docs/configuration/configuring-superset',
activeBaseRegex: '^/admin-docs/configuration/',
},
{
label: 'Database Drivers',
href: '/user-docs/databases/',
},
{
label: 'Security',
to: '/admin-docs/security/security',
activeBaseRegex: '^/admin-docs/security/',
},
],
});
}
// Add Developer Docs navbar item if not hidden from nav
if (!versionsConfig.developer_docs.disabled && !versionsConfig.developer_docs.hideFromNav) {
dynamicNavbarItems.push({
label: 'Developers',
to: '/developer-docs/',
position: 'left',
activeBaseRegex: '^/developer-docs/',
items: [
{
label: 'Overview',
to: '/developer-docs/',
activeBaseRegex: '^/developer-docs/$',
},
{
type: 'doc',
docsPluginId: 'developer_portal',
docId: 'contributing/overview',
label: 'Contributing',
to: '/developer-docs/contributing/overview',
activeBaseRegex: '^/developer-docs/contributing/',
},
{
type: 'doc',
docsPluginId: 'developer_portal',
docId: 'extensions/overview',
label: 'Extensions',
to: '/developer-docs/extensions/overview',
activeBaseRegex: '^/developer-docs/extensions/',
},
{
type: 'doc',
docsPluginId: 'developer_portal',
docId: 'testing/overview',
label: 'Testing',
to: '/developer-docs/testing/overview',
activeBaseRegex: '^/developer-docs/testing/',
},
{
type: 'doc',
docsPluginId: 'developer_portal',
docId: 'components/index',
label: 'UI Components',
to: '/developer-docs/components/',
activeBaseRegex: '^/developer-docs/components/',
},
{
label: 'API Reference',
href: '/docs/api',
to: '/developer-docs/api',
activeBaseRegex: '^/developer-docs/api',
},
],
});
@@ -271,11 +333,11 @@ const config: Config = {
'docusaurus-plugin-openapi-docs',
{
id: 'api',
docsPluginId: 'classic',
docsPluginId: 'developer_docs',
config: {
superset: {
specPath: 'static/resources/openapi.json',
outputDir: 'docs/api',
outputDir: 'developer_docs/api',
sidebarOptions: {
groupPathsBy: 'tag',
categoryLinkSource: 'tag',
@@ -307,147 +369,311 @@ const config: Config = {
'@docusaurus/plugin-client-redirects',
{
redirects: [
// Legacy HTML page redirects
{
to: '/docs/installation/docker-compose',
to: '/admin-docs/installation/docker-compose',
from: '/installation.html',
},
{
to: '/docs/intro',
to: '/user-docs/',
from: '/tutorials.html',
},
{
to: '/docs/using-superset/creating-your-first-dashboard',
to: '/user-docs/using-superset/creating-your-first-dashboard',
from: '/admintutorial.html',
},
{
to: '/docs/using-superset/creating-your-first-dashboard',
to: '/user-docs/using-superset/creating-your-first-dashboard',
from: '/usertutorial.html',
},
{
to: '/docs/security/',
to: '/admin-docs/security/',
from: '/security.html',
},
{
to: '/docs/configuration/sql-templating',
to: '/admin-docs/configuration/sql-templating',
from: '/sqllab.html',
},
{
to: '/docs/intro',
to: '/user-docs/',
from: '/gallery.html',
},
{
to: '/docs/databases',
to: '/user-docs/databases/',
from: '/druid.html',
},
{
to: '/docs/configuration/country-map-tools',
to: '/admin-docs/configuration/country-map-tools',
from: '/misc.html',
},
{
to: '/docs/configuration/country-map-tools',
to: '/admin-docs/configuration/country-map-tools',
from: '/visualization.html',
},
{
to: '/docs/faq',
to: '/user-docs/faq',
from: '/videos.html',
},
{
to: '/docs/faq',
to: '/user-docs/faq',
from: '/faq.html',
},
{
to: '/docs/using-superset/creating-your-first-dashboard',
to: '/user-docs/using-superset/creating-your-first-dashboard',
from: '/tutorial.html',
},
{
to: '/docs/using-superset/creating-your-first-dashboard',
to: '/user-docs/using-superset/creating-your-first-dashboard',
from: '/docs/creating-charts-dashboards/first-dashboard',
},
{
to: '/docs/api',
to: '/developer-docs/api',
from: '/docs/rest-api',
},
{
to: '/docs/configuration/alerts-reports',
to: '/admin-docs/configuration/alerts-reports',
from: '/docs/installation/alerts-reports',
},
{
to: '/docs/contributing/development',
to: '/developer-docs/contributing/development-setup',
from: '/docs/contributing/hooks-and-linting',
},
{
to: '/docs/intro',
to: '/user-docs/',
from: '/docs/roadmap',
},
{
to: '/docs/contributing/',
to: '/user-docs/',
from: '/user-docs/intro',
},
{
to: '/developer-docs/contributing/overview',
from: '/docs/contributing/contribution-guidelines',
},
{
to: '/docs/contributing/',
to: '/developer-docs/contributing/overview',
from: '/docs/contributing/contribution-page',
},
{
to: '/docs/databases',
to: '/user-docs/databases/',
from: '/docs/databases/yugabyte/',
},
{
to: '/docs/faq',
to: '/user-docs/faq',
from: '/docs/frequently-asked-questions',
},
// Redirect old user-docs/api to developer-docs/api
{
to: '/docs/installation/kubernetes',
to: '/developer-docs/api',
from: '/user-docs/api',
},
// Redirects from old /docs/ paths to new /admin-docs/ paths
{
to: '/admin-docs/installation/installation-methods',
from: '/docs/installation/installation-methods',
},
{
to: '/admin-docs/installation/docker-compose',
from: '/docs/installation/docker-compose',
},
{
to: '/admin-docs/installation/docker-builds',
from: '/docs/installation/docker-builds',
},
{
to: '/admin-docs/installation/kubernetes',
from: '/docs/installation/kubernetes',
},
{
to: '/admin-docs/installation/pypi',
from: '/docs/installation/pypi',
},
{
to: '/admin-docs/installation/architecture',
from: '/docs/installation/architecture',
},
{
to: '/admin-docs/installation/upgrading-superset',
from: '/docs/installation/upgrading-superset',
},
{
to: '/admin-docs/configuration/configuring-superset',
from: '/docs/configuration/configuring-superset',
},
{
to: '/admin-docs/configuration/alerts-reports',
from: '/docs/configuration/alerts-reports',
},
{
to: '/admin-docs/configuration/async-queries-celery',
from: '/docs/configuration/async-queries-celery',
},
{
to: '/admin-docs/configuration/cache',
from: '/docs/configuration/cache',
},
{
to: '/admin-docs/configuration/event-logging',
from: '/docs/configuration/event-logging',
},
{
to: '/admin-docs/configuration/feature-flags',
from: '/docs/configuration/feature-flags',
},
{
to: '/admin-docs/configuration/sql-templating',
from: '/docs/configuration/sql-templating',
},
{
to: '/admin-docs/configuration/theming',
from: '/docs/configuration/theming',
},
{
to: '/admin-docs/security/',
from: '/docs/security',
},
{
to: '/admin-docs/security/',
from: '/docs/security/security',
},
// Redirects from old /docs/contributing/ to Developer Portal
{
to: '/developer-docs/contributing/overview',
from: '/docs/contributing',
},
{
to: '/developer-docs/contributing/overview',
from: '/docs/contributing/contributing',
},
{
to: '/developer-docs/contributing/development-setup',
from: '/docs/contributing/development',
},
{
to: '/developer-docs/contributing/guidelines',
from: '/docs/contributing/guidelines',
},
{
to: '/developer-docs/contributing/howtos',
from: '/docs/contributing/howtos',
},
{
to: '/admin-docs/installation/kubernetes',
from: '/docs/installation/running-on-kubernetes/',
},
{
to: '/docs/contributing/howtos',
to: '/developer-docs/contributing/howtos',
from: '/docs/contributing/testing-locally/',
},
{
to: '/docs/using-superset/creating-your-first-dashboard',
to: '/user-docs/using-superset/creating-your-first-dashboard',
from: '/docs/creating-charts-dashboards/creating-your-first-dashboard/',
},
{
to: '/docs/using-superset/creating-your-first-dashboard',
to: '/user-docs/using-superset/creating-your-first-dashboard',
from: '/docs/creating-charts-dashboards/exploring-data/',
},
{
to: '/docs/installation/docker-compose',
to: '/admin-docs/installation/docker-compose',
from: '/docs/installation/installing-superset-using-docker-compose/',
},
{
to: '/docs/contributing/howtos',
to: '/developer-docs/contributing/howtos',
from: '/docs/contributing/creating-viz-plugins/',
},
{
to: '/docs/installation/kubernetes',
to: '/admin-docs/installation/kubernetes',
from: '/docs/installation/',
},
{
to: '/docs/installation/pypi',
to: '/admin-docs/installation/pypi',
from: '/docs/installation/installing-superset-from-pypi/',
},
{
to: '/docs/configuration/configuring-superset',
to: '/admin-docs/configuration/configuring-superset',
from: '/docs/installation/configuring-superset/',
},
{
to: '/docs/configuration/cache',
to: '/admin-docs/configuration/cache',
from: '/docs/installation/cache/',
},
{
to: '/docs/configuration/async-queries-celery',
to: '/admin-docs/configuration/async-queries-celery',
from: '/docs/installation/async-queries-celery/',
},
{
to: '/docs/configuration/event-logging',
to: '/admin-docs/configuration/event-logging',
from: '/docs/installation/event-logging/',
},
{
to: '/docs/contributing/howtos',
to: '/developer-docs/contributing/howtos',
from: '/docs/contributing/translations/',
},
// Additional configuration redirects
{
to: '/admin-docs/configuration/country-map-tools',
from: '/docs/configuration/country-map-tools',
},
{
to: '/admin-docs/configuration/importing-exporting-datasources',
from: '/docs/configuration/importing-exporting-datasources',
},
{
to: '/admin-docs/configuration/map-tiles',
from: '/docs/configuration/map-tiles',
},
{
to: '/admin-docs/configuration/networking-settings',
from: '/docs/configuration/networking-settings',
},
{
to: '/admin-docs/configuration/timezones',
from: '/docs/configuration/timezones',
},
// Additional security redirects
{
to: '/admin-docs/security/cves',
from: '/docs/security/cves',
},
{
to: '/admin-docs/security/securing_superset',
from: '/docs/security/securing_superset',
},
// Additional contributing redirects
{
to: '/developer-docs/contributing/resources',
from: '/docs/contributing/resources',
},
{
to: '/developer-docs/contributing/howtos',
from: '/docs/contributing/misc',
},
{
to: '/developer-docs/contributing/overview',
from: '/docs/contributing/pkg-resources-migration',
},
],
// Use createRedirects for pattern-based redirects
createRedirects(existingPath) {
const redirects = [];
// Redirect all /developer_portal/* paths to /developer-docs/*
if (existingPath.startsWith('/developer-docs/')) {
redirects.push(existingPath.replace('/developer-docs/', '/developer_portal/'));
}
// Redirect all /docs/* paths to /user-docs/* for user documentation
if (existingPath.startsWith('/user-docs/')) {
redirects.push(existingPath.replace('/user-docs/', '/docs/'));
}
// Redirect /docs/api/* to /developer-docs/api/* (API moved to developer docs)
if (existingPath.startsWith('/developer-docs/api')) {
redirects.push(existingPath.replace('/developer-docs/', '/docs/'));
}
return redirects.length > 0 ? redirects : undefined;
},
},
],
],
@@ -457,6 +683,7 @@ const config: Config = {
'@docusaurus/preset-classic',
{
docs: {
routeBasePath: 'user-docs',
sidebarPath: require.resolve('./sidebars.js'),
editUrl: ({ versionDocsDirPath, docPath }) => {
if (docPath === 'intro.md') {
@@ -476,7 +703,7 @@ const config: Config = {
disableVersioning: false,
showLastUpdateAuthor: true,
showLastUpdateTime: true,
docItemComponent: '@theme/ApiItem', // Required for OpenAPI docs
docItemComponent: '@theme/DocItem',
},
blog: {
showReadingTime: true,
@@ -499,19 +726,22 @@ const config: Config = {
const items = await defaultCreateSitemapItems(rest);
return items.map((item) => {
// Boost priority for key pages
if (item.url.includes('/docs/intro')) {
if (item.url.endsWith('/user-docs/')) {
return { ...item, priority: 1.0, changefreq: 'daily' };
}
if (item.url.includes('/docs/quickstart')) {
if (item.url.includes('/user-docs/quickstart')) {
return { ...item, priority: 0.9, changefreq: 'weekly' };
}
if (item.url.includes('/docs/installation/')) {
if (item.url.includes('/admin-docs/installation/')) {
return { ...item, priority: 0.8, changefreq: 'weekly' };
}
if (item.url.includes('/docs/databases')) {
if (item.url.includes('/user-docs/databases')) {
return { ...item, priority: 0.8, changefreq: 'weekly' };
}
if (item.url.includes('/docs/faq')) {
if (item.url.includes('/admin-docs/')) {
return { ...item, priority: 0.8, changefreq: 'weekly' };
}
if (item.url.includes('/user-docs/faq')) {
return { ...item, priority: 0.7, changefreq: 'monthly' };
}
if (item.url === 'https://superset.apache.org/') {
@@ -562,34 +792,50 @@ const config: Config = {
srcDark: '/img/superset-logo-horiz-dark.svg',
},
items: [
// Users docs - mirrors sidebar structure
{
label: 'Documentation',
label: 'Users',
to: '/user-docs/',
position: 'left',
activeBaseRegex: '^/user-docs/',
items: [
{
type: 'doc',
docId: 'intro',
label: 'Getting Started',
label: 'Overview',
to: '/user-docs/',
activeBaseRegex: '^/user-docs/$',
},
{
type: 'doc',
docId: 'databases/index',
label: 'Databases',
label: 'Quickstart',
to: '/user-docs/quickstart',
},
{
label: 'Using Superset',
to: '/user-docs/using-superset/creating-your-first-dashboard',
activeBaseRegex: '^/user-docs/using-superset/',
},
{
label: 'Connecting to Databases',
to: '/user-docs/databases/',
activeBaseRegex: '^/user-docs/databases/',
},
{
type: 'doc',
docId: 'faq',
label: 'FAQ',
to: '/user-docs/faq',
},
],
},
...dynamicNavbarItems,
// Community section
{
label: 'Community Resources',
label: 'Community',
to: '/community',
position: 'left',
activeBaseRegex: '^/community',
items: [
{
label: 'Resources',
href: '/community',
to: '/community',
activeBaseRegex: '^/community$',
},
{
label: 'GitHub',
@@ -617,9 +863,8 @@ const config: Config = {
},
],
},
...dynamicNavbarItems,
{
href: '/docs/intro',
href: '/user-docs/',
position: 'right',
className: 'default-button-theme get-started-button',
label: 'Get Started',
@@ -646,7 +891,7 @@ const config: Config = {
<img class="footer__divider" src="/img/community/line.png" alt="Divider" />
<p>
<small>
<a href="/docs/security/" target="_blank" rel="noreferrer">Security</a>&nbsp;|&nbsp;
<a href="/admin-docs/security/" target="_blank" rel="noreferrer">Security</a>&nbsp;|&nbsp;
<a href="https://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noreferrer">Donate</a>&nbsp;|&nbsp;
<a href="https://www.apache.org/foundation/thanks.html" target="_blank" rel="noreferrer">Thanks</a>&nbsp;|&nbsp;
<a href="https://apache.org/events/current-event" target="_blank" rel="noreferrer">Events</a>&nbsp;|&nbsp;