From 0a45a89786cc7450aba67d025c6541fde471c00f Mon Sep 17 00:00:00 2001 From: Evan Rusackas Date: Fri, 22 Aug 2025 09:53:01 -0700 Subject: [PATCH] feat(docs): Docusaurus multi-versioning, Developer Portal starter kit (#34271) Co-authored-by: Claude --- docs/README.md | 180 + docs/components/chart-components/bar-chart.md | 105 + docs/components/index.md | 59 + docs/components/layout-components/grid.md | 113 + docs/components/test.mdx | 35 + docs/components/ui-components/button.mdx | 146 + docs/components/versions.json | 1 + docs/components_versions.json | 1 + docs/developer_portal/api/frontend.md | 477 ++ .../developer_portal/architecture/overview.md | 348 ++ docs/developer_portal/cli/overview.md | 466 ++ docs/developer_portal/examples/index.md | 464 ++ .../developer_portal/getting-started/index.md | 248 + docs/developer_portal/index.md | 126 + docs/developer_portal/sidebars.js | 59 + docs/developer_portal/versions.json | 1 + docs/developer_portal_versions.json | 1 + docs/docusaurus.config.ts | 141 +- docs/package.json | 40 +- docs/scripts/manage-versions.mjs | 242 + docs/sidebarComponents.js | 68 + docs/sidebarTutorials.js | 48 + docs/src/components/Button.jsx | 23 + docs/src/components/StorybookWrapper.jsx | 121 + docs/src/pages/index.tsx | 20 +- docs/src/styles/custom.css | 54 + docs/src/theme/DocVersionBadge/index.js | 119 + .../theme/DocVersionBadge/styles.module.css | 42 + docs/src/theme/DocVersionBanner/index.js | 121 + .../theme/DocVersionBanner/styles.module.css | 49 + docs/src/webpack.extend.ts | 115 + docs/tutorials_versions.json | 3 + docs/versioned_docs/version-6.0.0/api.mdx | 35 + .../configuration/alerts-reports.mdx | 436 ++ .../configuration/async-queries-celery.mdx | 104 + .../version-6.0.0/configuration/cache.mdx | 154 + .../configuration/configuring-superset.mdx | 548 ++ .../configuration/country-map-tools.mdx | 40 + .../version-6.0.0/configuration/databases.mdx | 1815 +++++++ .../configuration/event-logging.mdx | 62 + .../importing-exporting-datasources.mdx | 126 + .../version-6.0.0/configuration/map-tiles.mdx | 78 + .../configuration/networking-settings.mdx | 141 + .../configuration/sql-templating.mdx | 535 ++ .../version-6.0.0/configuration/theming.mdx | 192 + .../version-6.0.0/configuration/timezones.mdx | 50 + .../contributing/contributing.mdx | 138 + .../contributing/development.mdx | 1069 ++++ .../version-6.0.0/contributing/guidelines.mdx | 254 + .../version-6.0.0/contributing/howtos.mdx | 634 +++ .../version-6.0.0/contributing/misc.mdx | 55 + .../version-6.0.0/contributing/resources.mdx | 104 + docs/versioned_docs/version-6.0.0/faq.mdx | 285 + .../installation/architecture.mdx | 72 + .../installation/docker-builds.mdx | 175 + .../installation/docker-compose.mdx | 286 + .../installation/installation-methods.mdx | 56 + .../version-6.0.0/installation/kubernetes.mdx | 446 ++ .../version-6.0.0/installation/pypi.mdx | 164 + .../installation/upgrading-superset.mdx | 49 + docs/versioned_docs/version-6.0.0/intro.md | 227 + .../version-6.0.0/quickstart.mdx | 82 + .../version-6.0.0/security/cves.mdx | 130 + .../version-6.0.0/security/security.mdx | 362 ++ .../creating-your-first-dashboard.mdx | 231 + .../using-superset/exploring-data.mdx | 328 ++ .../using-superset/issue-codes.mdx | 334 ++ .../version-6.0.0-sidebars.json | 74 + docs/versions-config.json | 53 + docs/versions.json | 3 + docs/yarn.lock | 4637 ++++++++++------- 71 files changed, 16791 insertions(+), 1809 deletions(-) create mode 100644 docs/components/chart-components/bar-chart.md create mode 100644 docs/components/index.md create mode 100644 docs/components/layout-components/grid.md create mode 100644 docs/components/test.mdx create mode 100644 docs/components/ui-components/button.mdx create mode 100644 docs/components/versions.json create mode 100644 docs/components_versions.json create mode 100644 docs/developer_portal/api/frontend.md create mode 100644 docs/developer_portal/architecture/overview.md create mode 100644 docs/developer_portal/cli/overview.md create mode 100644 docs/developer_portal/examples/index.md create mode 100644 docs/developer_portal/getting-started/index.md create mode 100644 docs/developer_portal/index.md create mode 100644 docs/developer_portal/sidebars.js create mode 100644 docs/developer_portal/versions.json create mode 100644 docs/developer_portal_versions.json create mode 100644 docs/scripts/manage-versions.mjs create mode 100644 docs/sidebarComponents.js create mode 100644 docs/sidebarTutorials.js create mode 100644 docs/src/components/Button.jsx create mode 100644 docs/src/components/StorybookWrapper.jsx create mode 100644 docs/src/theme/DocVersionBadge/index.js create mode 100644 docs/src/theme/DocVersionBadge/styles.module.css create mode 100644 docs/src/theme/DocVersionBanner/index.js create mode 100644 docs/src/theme/DocVersionBanner/styles.module.css create mode 100644 docs/src/webpack.extend.ts create mode 100644 docs/tutorials_versions.json create mode 100644 docs/versioned_docs/version-6.0.0/api.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/alerts-reports.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/async-queries-celery.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/cache.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/configuring-superset.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/country-map-tools.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/databases.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/event-logging.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/importing-exporting-datasources.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/map-tiles.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/networking-settings.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/sql-templating.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/theming.mdx create mode 100644 docs/versioned_docs/version-6.0.0/configuration/timezones.mdx create mode 100644 docs/versioned_docs/version-6.0.0/contributing/contributing.mdx create mode 100644 docs/versioned_docs/version-6.0.0/contributing/development.mdx create mode 100644 docs/versioned_docs/version-6.0.0/contributing/guidelines.mdx create mode 100644 docs/versioned_docs/version-6.0.0/contributing/howtos.mdx create mode 100644 docs/versioned_docs/version-6.0.0/contributing/misc.mdx create mode 100644 docs/versioned_docs/version-6.0.0/contributing/resources.mdx create mode 100644 docs/versioned_docs/version-6.0.0/faq.mdx create mode 100644 docs/versioned_docs/version-6.0.0/installation/architecture.mdx create mode 100644 docs/versioned_docs/version-6.0.0/installation/docker-builds.mdx create mode 100644 docs/versioned_docs/version-6.0.0/installation/docker-compose.mdx create mode 100644 docs/versioned_docs/version-6.0.0/installation/installation-methods.mdx create mode 100644 docs/versioned_docs/version-6.0.0/installation/kubernetes.mdx create mode 100644 docs/versioned_docs/version-6.0.0/installation/pypi.mdx create mode 100644 docs/versioned_docs/version-6.0.0/installation/upgrading-superset.mdx create mode 100644 docs/versioned_docs/version-6.0.0/intro.md create mode 100644 docs/versioned_docs/version-6.0.0/quickstart.mdx create mode 100644 docs/versioned_docs/version-6.0.0/security/cves.mdx create mode 100644 docs/versioned_docs/version-6.0.0/security/security.mdx create mode 100644 docs/versioned_docs/version-6.0.0/using-superset/creating-your-first-dashboard.mdx create mode 100644 docs/versioned_docs/version-6.0.0/using-superset/exploring-data.mdx create mode 100644 docs/versioned_docs/version-6.0.0/using-superset/issue-codes.mdx create mode 100644 docs/versioned_sidebars/version-6.0.0-sidebars.json create mode 100644 docs/versions-config.json create mode 100644 docs/versions.json diff --git a/docs/README.md b/docs/README.md index ef5db9ebfd7..8af3ea90da5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,3 +21,183 @@ This is the public documentation site for Superset, built using [Docusaurus 3](https://docusaurus.io/). See [CONTRIBUTING.md](../CONTRIBUTING.md#documentation) for documentation on contributing to documentation. + +## Version Management + +The Superset documentation site uses Docusaurus versioning with three independent versioned sections: + +- **Main Documentation** (`/docs/`) - Core Superset documentation +- **Developer Portal** (`/developer_portal/`) - Developer guides and tutorials +- **Component Playground** (`/components/`) - Interactive component examples (currently disabled) + +Each section maintains its own version history and can be versioned independently. + +### Creating a New Version + +To create a new version for any section, use the Docusaurus version command with the appropriate plugin ID or use our automated scripts: + +#### Using Automated Scripts (Required) + +**⚠️ Important:** Always use these custom commands instead of the native Docusaurus commands. These scripts ensure that both the Docusaurus versioning system AND the `versions-config.json` file are updated correctly. + +```bash +# Main Documentation +yarn version:add:docs 1.2.0 + +# Developer Portal +yarn version:add:developer_portal 1.2.0 + +# Component Playground (when enabled) +yarn version:add:components 1.2.0 +``` + +**Do NOT use** the native Docusaurus commands directly (`yarn docusaurus docs:version`), as they will: +- ❌ Create version files but NOT update `versions-config.json` +- ❌ Cause versions to not appear in dropdown menus +- ❌ Require manual fixes to synchronize the configuration + +### Managing Versions + +#### With Automated Scripts +The automated scripts handle all configuration updates automatically. No manual editing required! + +#### Manual Configuration +If creating versions manually, you'll need to: + +1. **Update `versions-config.json`** (or `docusaurus.config.ts` if not using dynamic config): + - Add version to `onlyIncludeVersions` array + - Add version metadata to `versions` object + - Update `lastVersion` if needed + +2. **Files Created by Versioning**: + When a new version is created, Docusaurus generates: + - **Versioned docs folder**: `[section]_versioned_docs/version-X.X.X/` + - **Versioned sidebars**: `[section]_versioned_sidebars/version-X.X.X-sidebars.json` + - **Versions list**: `[section]_versions.json` + + Note: For main docs, the prefix is omitted (e.g., `versioned_docs/` instead of `docs_versioned_docs/`) + +3. **Important**: After adding a version, restart the development server to see changes: + ```bash + yarn stop + yarn start + ``` + +### Removing a Version + +#### Using Automated Scripts (Recommended) +```bash +# Main Documentation +yarn version:remove:docs 1.0.0 + +# Developer Portal +yarn version:remove:developer_portal 1.0.0 + +# Component Playground +yarn version:remove:components 1.0.0 +``` + +#### Manual Removal +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/` + - 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` + - 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` + - Components: `components_versions.json` + +4. **Update configuration**: + - If using dynamic config: Update `versions-config.json` + - If using static config: Update `docusaurus.config.ts` + +5. **Restart the server** to see changes + +### Version Configuration Examples + +#### Main Documentation (default plugin) +```typescript +docs: { + includeCurrentVersion: true, + lastVersion: 'current', // Makes /docs/ show Next version + onlyIncludeVersions: ['current', '1.1.0', '1.0.0'], + versions: { + current: { + label: 'Next', + path: '', // Empty path for default routing + banner: 'unreleased', + }, + '1.1.0': { + label: '1.1.0', + path: '1.1.0', + banner: 'none', + }, + }, +} +``` + +#### Developer Portal & Components (custom plugins) +```typescript +{ + id: 'developer_portal', + path: 'developer_portal', + routeBasePath: 'developer_portal', + includeCurrentVersion: true, + lastVersion: '1.1.0', // Default version + onlyIncludeVersions: ['current', '1.1.0', '1.0.0'], + versions: { + current: { + label: 'Next', + path: 'next', + banner: 'unreleased', + }, + '1.1.0': { + label: '1.1.0', + path: '1.1.0', + banner: 'none', + }, + }, +} +``` + +### Best Practices + +1. **Version naming**: Use semantic versioning (e.g., 1.0.0, 1.1.0, 2.0.0) +2. **Version banners**: Use `'unreleased'` for development versions, `'none'` for stable releases +3. **Limit displayed versions**: Use `onlyIncludeVersions` to show only relevant versions +4. **Test locally**: Always test version changes locally before deploying +5. **Independent versioning**: Each section can have different version numbers and release cycles + +### Troubleshooting + +#### Version Not Showing After Creation + +If you accidentally used `yarn docusaurus docs:version` instead of `yarn version:add`: +1. **Problem**: The version files were created but `versions-config.json` wasn't updated +2. **Solution**: Either: + - Revert the changes: `git restore versions.json && rm -rf versioned_docs/ versioned_sidebars/` + - Then use the correct command: `yarn version:add:docs ` + +For other issues: +- **Restart the server**: Changes to version configuration require a server restart +- **Check config file**: Ensure `versions-config.json` includes the new version +- **Verify files exist**: Check that versioned docs folder was created + +#### 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 +- **Absolute vs relative paths**: Use relative paths within the same section +- **Version-specific URLs**: Update hardcoded URLs to use version variables + +To fix broken links: +1. Use `type: 'doc'` with `docId` for version-aware navigation in navbar +2. Use relative paths within the same documentation section +3. Test all versions after creation to identify broken links diff --git a/docs/components/chart-components/bar-chart.md b/docs/components/chart-components/bar-chart.md new file mode 100644 index 00000000000..2b8e336e6ea --- /dev/null +++ b/docs/components/chart-components/bar-chart.md @@ -0,0 +1,105 @@ + +--- +title: Bar Chart +sidebar_position: 1 +--- + +# Bar Chart Component + +The Bar Chart component is used to visualize categorical data with rectangular bars. + +## Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `data` | `array` | `[]` | Array of data objects to visualize | +| `width` | `number` | `800` | Width of the chart in pixels | +| `height` | `number` | `600` | Height of the chart in pixels | +| `xField` | `string` | - | Field name for x-axis values | +| `yField` | `string` | - | Field name for y-axis values | +| `colorField` | `string` | - | Field name for color encoding | +| `colorScheme` | `string` | `'supersetColors'` | Color scheme to use | +| `showLegend` | `boolean` | `true` | Whether to show the legend | +| `showGrid` | `boolean` | `true` | Whether to show grid lines | +| `labelPosition` | `string` | `'top'` | Position of bar labels: 'top', 'middle', 'bottom' | + +## Examples + +### Basic Bar Chart + +```jsx +import { BarChart } from '@superset-ui/chart-components'; + +const data = [ + { category: 'A', value: 10 }, + { category: 'B', value: 20 }, + { category: 'C', value: 15 }, + { category: 'D', value: 25 }, +]; + +function Example() { + return ( + + ); +} +``` + +### Grouped Bar Chart + +```jsx +import { BarChart } from '@superset-ui/chart-components'; + +const data = [ + { category: 'A', group: 'Group 1', value: 10 }, + { category: 'A', group: 'Group 2', value: 15 }, + { category: 'B', group: 'Group 1', value: 20 }, + { category: 'B', group: 'Group 2', value: 25 }, + { category: 'C', group: 'Group 1', value: 15 }, + { category: 'C', group: 'Group 2', value: 10 }, +]; + +function Example() { + return ( + + ); +} +``` + +## Best Practices + +- Use bar charts when comparing quantities across categories +- Sort bars by value for better readability, unless there's a natural order to the categories +- Use consistent colors for the same categories across different charts +- Consider using horizontal bar charts when category labels are long diff --git a/docs/components/index.md b/docs/components/index.md new file mode 100644 index 00000000000..77fb2a9cca9 --- /dev/null +++ b/docs/components/index.md @@ -0,0 +1,59 @@ + +--- +title: Component Library +sidebar_position: 1 +--- + +# Superset Component Library + +Welcome to the Apache Superset Component Library documentation. This section provides comprehensive documentation for all the UI components, chart components, and layout components used in Superset. + +## What is the Component Library? + +The Component Library is a collection of reusable UI components that are used to build the Superset user interface. These components are designed to be consistent, accessible, and easy to use. + +## Component Categories + +The Component Library is organized into the following categories: + +### UI Components + +Basic UI components like buttons, inputs, dropdowns, and other form elements. + +### Chart Components + +Visualization components used to render different types of charts and graphs. + +### Layout Components + +Components used for page layout, such as containers, grids, and navigation elements. + +## Versioning + +The Component Library documentation follows its own versioning scheme, independent from the main Superset documentation. This allows us to update the component documentation as the components evolve, without affecting the main documentation. + +## Getting Started + +Browse the sidebar to explore the different components available in the library. Each component documentation includes: + +- Component description and purpose +- Props and configuration options +- Usage examples +- Best practices diff --git a/docs/components/layout-components/grid.md b/docs/components/layout-components/grid.md new file mode 100644 index 00000000000..a0980d2bdcf --- /dev/null +++ b/docs/components/layout-components/grid.md @@ -0,0 +1,113 @@ + +--- +title: Grid +sidebar_position: 1 +--- + +# Grid Component + +The Grid component provides a flexible layout system for arranging content in rows and columns. + +## Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `gutter` | `number` or `[number, number]` | `0` | Grid spacing between items, can be a single number or [horizontal, vertical] | +| `columns` | `number` | `12` | Number of columns in the grid | +| `justify` | `string` | `'start'` | Horizontal alignment: 'start', 'center', 'end', 'space-between', 'space-around' | +| `align` | `string` | `'top'` | Vertical alignment: 'top', 'middle', 'bottom' | +| `wrap` | `boolean` | `true` | Whether to wrap items when they overflow | + +### Row Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `gutter` | `number` or `[number, number]` | `0` | Spacing between items in the row | +| `justify` | `string` | `'start'` | Horizontal alignment for this row | +| `align` | `string` | `'top'` | Vertical alignment for this row | + +### Col Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `span` | `number` | - | Number of columns the grid item spans | +| `offset` | `number` | `0` | Number of columns the grid item is offset | +| `xs`, `sm`, `md`, `lg`, `xl` | `number` or `object` | - | Responsive props for different screen sizes | + +## Examples + +### Basic Grid + +```jsx +import { Grid, Row, Col } from '@superset-ui/core'; + +function Example() { + return ( + + + +
Column 1
+ + +
Column 2
+ + +
Column 3
+ + + + ); +} +``` + +### Responsive Grid + +```jsx +import { Grid, Row, Col } from '@superset-ui/core'; + +function Example() { + return ( + + + +
Responsive Column 1
+ + +
Responsive Column 2
+ + +
Responsive Column 3
+ + +
Responsive Column 4
+ + + + ); +} +``` + +## Best Practices + +- Use the Grid system for complex layouts that need to be responsive +- Specify column widths for different screen sizes to ensure proper responsive behavior +- Use gutters to create appropriate spacing between grid items +- Keep the grid structure consistent throughout your application +- Consider using the grid system for dashboard layouts to ensure consistent spacing and alignment diff --git a/docs/components/test.mdx b/docs/components/test.mdx new file mode 100644 index 00000000000..d5f842ad631 --- /dev/null +++ b/docs/components/test.mdx @@ -0,0 +1,35 @@ + +--- +title: Test +--- + +import { StoryExample } from '../src/components/StorybookWrapper'; + +# Test + +This is a test using our custom StorybookWrapper component. + + ( +
+ This is a simple example component +
+ )} +/> diff --git a/docs/components/ui-components/button.mdx b/docs/components/ui-components/button.mdx new file mode 100644 index 00000000000..2102d146efe --- /dev/null +++ b/docs/components/ui-components/button.mdx @@ -0,0 +1,146 @@ + +--- +title: Button Component +sidebar_position: 1 +--- + +import { StoryExample, StoryWithControls } from '../../src/components/StorybookWrapper'; +import { Button } from '../../../superset-frontend/packages/superset-ui-core/src/components/Button'; + +# Button Component + +The Button component is a fundamental UI element used throughout Superset for user interactions. + +## Basic Usage + +The default button with primary styling: + ( + + )} +/> + +## Interactive Example + + ( + + )} + props={{ + buttonStyle: 'primary', + buttonSize: 'default', + label: 'Click Me', + disabled: false + }} + controls={[ + { + name: 'buttonStyle', + label: 'Button Style', + type: 'select', + options: ['primary', 'secondary', 'tertiary', 'success', 'warning', 'danger', 'default', 'link', 'dashed'] + }, + { + name: 'buttonSize', + label: 'Button Size', + type: 'select', + options: ['default', 'small', 'xsmall'] + }, + { + name: 'label', + label: 'Button Text', + type: 'text' + }, + { + name: 'disabled', + label: 'Disabled', + type: 'boolean' + } + ]} +/> + +## Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `buttonStyle` | `'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'danger' \| 'default' \| 'link' \| 'dashed'` | `'default'` | Button style | +| `buttonSize` | `'default' \| 'small' \| 'xsmall'` | `'default'` | Button size | +| `disabled` | `boolean` | `false` | Whether the button is disabled | +| `cta` | `boolean` | `false` | Whether the button is a call-to-action button | +| `tooltip` | `ReactNode` | - | Tooltip content | +| `placement` | `TooltipProps['placement']` | - | Tooltip placement | +| `onClick` | `function` | - | Callback when button is clicked | +| `href` | `string` | - | Turns button into an anchor link | +| `target` | `string` | - | Target attribute for anchor links | + +## Usage + +```jsx +import Button from 'src/components/Button'; + +function MyComponent() { + return ( + + ); +} +``` + +## Button Styles + +Superset provides a variety of button styles for different purposes: + +- **Primary**: Used for primary actions +- **Secondary**: Used for secondary actions +- **Tertiary**: Used for less important actions +- **Success**: Used for successful or confirming actions +- **Warning**: Used for actions that require caution +- **Danger**: Used for destructive actions +- **Link**: Used for navigation +- **Dashed**: Used for adding new items or features + +## Button Sizes + +Buttons come in three sizes: + +- **Default**: Standard size for most use cases +- **Small**: Compact size for tight spaces +- **XSmall**: Extra small size for very limited spaces + +## Best Practices + +- Use primary buttons for the main action in a form or page +- Use secondary buttons for alternative actions +- Use danger buttons for destructive actions +- Limit the number of primary buttons on a page to avoid confusion +- Use consistent button styles throughout your application +- Add tooltips to buttons when their purpose might not be immediately clear diff --git a/docs/components/versions.json b/docs/components/versions.json new file mode 100644 index 00000000000..fe51488c706 --- /dev/null +++ b/docs/components/versions.json @@ -0,0 +1 @@ +[] diff --git a/docs/components_versions.json b/docs/components_versions.json new file mode 100644 index 00000000000..fe51488c706 --- /dev/null +++ b/docs/components_versions.json @@ -0,0 +1 @@ +[] diff --git a/docs/developer_portal/api/frontend.md b/docs/developer_portal/api/frontend.md new file mode 100644 index 00000000000..e2d66ae9f0a --- /dev/null +++ b/docs/developer_portal/api/frontend.md @@ -0,0 +1,477 @@ +--- +title: Frontend API Reference +sidebar_position: 1 +hide_title: true +--- + + + +# Frontend API Reference + +The `@apache-superset/core` package provides comprehensive APIs for frontend extension development. All APIs are organized into logical namespaces for easy discovery and use. + +## Core API + +The core namespace provides fundamental extension functionality. + +### registerView + +Registers a new view or panel in the specified contribution point. + +```typescript +core.registerView( + id: string, + component: React.ComponentType +): Disposable +``` + +**Example:** +```typescript +const panel = context.core.registerView('my-extension.panel', () => ( + +)); +``` + +### getActiveView + +Gets the currently active view in a contribution area. + +```typescript +core.getActiveView(area: string): View | undefined +``` + +## Commands API + +Manages command registration and execution. + +### registerCommand + +Registers a new command that can be triggered by menus, shortcuts, or programmatically. + +```typescript +commands.registerCommand( + id: string, + handler: CommandHandler +): Disposable + +interface CommandHandler { + title: string; + icon?: string; + execute: (...args: any[]) => any; + isEnabled?: (...args: any[]) => boolean; +} +``` + +**Example:** +```typescript +const cmd = context.commands.registerCommand('my-extension.analyze', { + title: 'Analyze Query', + icon: 'BarChartOutlined', + execute: () => { + const query = context.sqlLab.getCurrentQuery(); + // Perform analysis + }, + isEnabled: () => { + return context.sqlLab.hasActiveEditor(); + } +}); +``` + +### executeCommand + +Executes a registered command by ID. + +```typescript +commands.executeCommand(id: string, ...args: any[]): Promise +``` + +## SQL Lab API + +Provides access to SQL Lab functionality and events. + +### Query Access + +```typescript +// Get current tab +sqlLab.getCurrentTab(): Tab | undefined + +// Get all tabs +sqlLab.getTabs(): Tab[] + +// Get current query +sqlLab.getCurrentQuery(): string + +// Get selected text +sqlLab.getSelectedText(): string | undefined +``` + +### Database Access + +```typescript +// Get available databases +sqlLab.getDatabases(): Database[] + +// Get database by ID +sqlLab.getDatabase(id: number): Database | undefined + +// Get schemas for database +sqlLab.getSchemas(databaseId: number): Promise + +// Get tables for schema +sqlLab.getTables( + databaseId: number, + schema: string +): Promise +``` + +### Events + +```typescript +// Query execution events +sqlLab.onDidQueryRun: Event +sqlLab.onDidQueryStop: Event +sqlLab.onDidQueryFail: Event + +// Editor events +sqlLab.onDidChangeEditorContent: Event +sqlLab.onDidChangeSelection: Event + +// Tab events +sqlLab.onDidChangeActiveTab: Event +sqlLab.onDidCloseTab: Event +sqlLab.onDidChangeTabTitle: Event<{tab: Tab, title: string}> + +// Panel events +sqlLab.onDidOpenPanel: Event +sqlLab.onDidClosePanel: Event +sqlLab.onDidChangeActivePanel: Event +``` + +**Event Usage Example:** +```typescript +const disposable = context.sqlLab.onDidQueryRun((result) => { + console.log('Query executed:', result.query); + console.log('Rows returned:', result.rowCount); + console.log('Execution time:', result.executionTime); +}); + +// Remember to dispose when done +context.subscriptions.push(disposable); +``` + +## Authentication API + +Handles authentication and security tokens. + +### getCSRFToken + +Gets the current CSRF token for API requests. + +```typescript +authentication.getCSRFToken(): Promise +``` + +### getCurrentUser + +Gets information about the current user. + +```typescript +authentication.getCurrentUser(): User + +interface User { + id: number; + username: string; + email: string; + roles: Role[]; + permissions: Permission[]; +} +``` + +### hasPermission + +Checks if the current user has a specific permission. + +```typescript +authentication.hasPermission(permission: string): boolean +``` + +## Extensions API + +Manages extension lifecycle and inter-extension communication. + +### getExtension + +Gets information about an installed extension. + +```typescript +extensions.getExtension(id: string): Extension | undefined + +interface Extension { + id: string; + name: string; + version: string; + isActive: boolean; + metadata: ExtensionMetadata; +} +``` + +### getActiveExtensions + +Gets all currently active extensions. + +```typescript +extensions.getActiveExtensions(): Extension[] +``` + +### Events + +```typescript +// Extension lifecycle events +extensions.onDidActivateExtension: Event +extensions.onDidDeactivateExtension: Event +``` + +## UI Components + +Import pre-built UI components from `@apache-superset/core`: + +```typescript +import { + Button, + Select, + Input, + Table, + Modal, + Alert, + Tabs, + Card, + Dropdown, + Menu, + Tooltip, + Icon, + // ... many more +} from '@apache-superset/core'; +``` + +### Example Component Usage + +```typescript +import { Button, Alert } from '@apache-superset/core'; + +function MyExtensionPanel() { + return ( +
+ + +
+ ); +} +``` + +## Storage API + +Provides persistent storage for extension data. + +### Local Storage + +```typescript +// Store data +storage.local.set(key: string, value: any): Promise + +// Retrieve data +storage.local.get(key: string): Promise + +// Remove data +storage.local.remove(key: string): Promise + +// Clear all extension data +storage.local.clear(): Promise +``` + +### Workspace Storage + +Workspace storage is shared across all users for collaborative features. + +```typescript +storage.workspace.set(key: string, value: any): Promise +storage.workspace.get(key: string): Promise +storage.workspace.remove(key: string): Promise +``` + +## Network API + +Utilities for making API calls to Superset. + +### fetch + +Enhanced fetch with CSRF token handling. + +```typescript +network.fetch(url: string, options?: RequestInit): Promise +``` + +### API Client + +Type-safe API client for Superset endpoints. + +```typescript +// Get chart data +network.api.charts.get(id: number): Promise + +// Query database +network.api.sqlLab.execute( + databaseId: number, + query: string +): Promise + +// Get datasets +network.api.datasets.list(): Promise +``` + +## Utility Functions + +### Formatting + +```typescript +// Format numbers +utils.formatNumber(value: number, format?: string): string + +// Format dates +utils.formatDate(date: Date, format?: string): string + +// Format SQL +utils.formatSQL(sql: string): string +``` + +### Validation + +```typescript +// Validate SQL syntax +utils.validateSQL(sql: string): ValidationResult + +// Check if valid database ID +utils.isValidDatabaseId(id: any): boolean +``` + +## TypeScript Types + +Import common types for type safety: + +```typescript +import type { + Database, + Dataset, + Chart, + Dashboard, + Query, + QueryResult, + Tab, + Panel, + User, + Role, + Permission, + ExtensionContext, + Disposable, + Event, + // ... more types +} from '@apache-superset/core'; +``` + +## Extension Context + +The context object passed to your extension's `activate` function: + +```typescript +interface ExtensionContext { + // Subscription management + subscriptions: Disposable[]; + + // Extension metadata + extensionId: string; + extensionPath: string; + + // API namespaces + core: CoreAPI; + commands: CommandsAPI; + sqlLab: SqlLabAPI; + authentication: AuthenticationAPI; + extensions: ExtensionsAPI; + storage: StorageAPI; + network: NetworkAPI; + utils: UtilsAPI; + + // Logging + logger: Logger; +} +``` + +## Event Handling + +Events follow the VS Code pattern with subscribe/dispose: + +```typescript +// Subscribe to event +const disposable = sqlLab.onDidQueryRun((result) => { + // Handle event +}); + +// Dispose when done +disposable.dispose(); + +// Or add to context for automatic cleanup +context.subscriptions.push(disposable); +``` + +## Best Practices + +1. **Always dispose subscriptions** to prevent memory leaks +2. **Use TypeScript** for better IDE support and type safety +3. **Handle errors gracefully** with try-catch blocks +4. **Check permissions** before sensitive operations +5. **Use provided UI components** for consistency +6. **Cache API responses** when appropriate +7. **Validate user input** before processing + +## Version Compatibility + +The frontend API follows semantic versioning: + +- **Major version**: Breaking changes +- **Minor version**: New features, backward compatible +- **Patch version**: Bug fixes + +Check compatibility in your `extension.json`: + +```json +{ + "engines": { + "@apache-superset/core": "^1.0.0" + } +} +``` diff --git a/docs/developer_portal/architecture/overview.md b/docs/developer_portal/architecture/overview.md new file mode 100644 index 00000000000..452e8fe1688 --- /dev/null +++ b/docs/developer_portal/architecture/overview.md @@ -0,0 +1,348 @@ +--- +title: Architecture Overview +sidebar_position: 1 +hide_title: true +--- + + + +# Extension Architecture Overview + +The Superset extension architecture is designed to be modular, secure, and performant. This document provides a comprehensive overview of how extensions work and interact with the Superset host application. + +## Core Principles + +### 1. Lean Core +Superset's core remains minimal, with features delegated to extensions wherever possible. Built-in features use the same APIs as external extensions, ensuring API quality through dogfooding. + +### 2. Explicit Contribution Points +All extension points are clearly defined and documented. Extensions declare their capabilities in metadata files, enabling predictable lifecycle management. + +### 3. Versioned APIs +Public interfaces follow semantic versioning, ensuring backward compatibility and safe evolution of the platform. + +### 4. Lazy Loading +Extensions load only when needed, minimizing performance impact and resource consumption. + +### 5. Composability +Architecture patterns and APIs are reusable across different Superset modules, promoting consistency. + +### 6. Community-Driven +The system evolves based on real-world feedback, with new extension points added as needs emerge. + +## System Architecture + +```mermaid +graph TB + subgraph "Superset Host Application" + Core[Core Application] + API[Extension APIs] + Loader[Extension Loader] + Manager[Extension Manager] + end + + subgraph "Core Packages" + FrontendCore["@apache-superset/core
(Frontend)"] + BackendCore["apache-superset-core
(Backend)"] + CLI["apache-superset-extensions-cli"] + end + + subgraph "Extension" + Metadata[extension.json] + Frontend[Frontend Code] + Backend[Backend Code] + Bundle[.supx Bundle] + end + + Core --> API + API --> FrontendCore + API --> BackendCore + Loader --> Manager + Manager --> Bundle + Frontend --> FrontendCore + Backend --> BackendCore + CLI --> Bundle +``` + +## Key Components + +### Host Application + +The Superset host application provides: + +- **Extension APIs**: Well-defined interfaces for extensions to interact with Superset +- **Extension Manager**: Handles lifecycle, activation, and deactivation +- **Module Loader**: Dynamically loads extension code using Webpack Module Federation +- **Security Context**: Manages permissions and sandboxing for extensions + +### Core Packages + +#### @apache-superset/core (Frontend) +- Shared UI components and utilities +- TypeScript type definitions +- Frontend API implementations +- Event system and command registry + +#### apache-superset-core (Backend) +- Python base classes and utilities +- Database access APIs +- Security and permission helpers +- REST API registration + +#### apache-superset-extensions-cli +- Project scaffolding +- Build and bundling tools +- Development server +- Package management + +### Extension Structure + +Each extension consists of: + +- **Metadata** (`extension.json`): Declares capabilities and requirements +- **Frontend**: React components and TypeScript code +- **Backend**: Python modules and API endpoints +- **Assets**: Styles, images, and other resources +- **Bundle** (`.supx`): Packaged distribution format + +## Module Federation + +Extensions use Webpack Module Federation for dynamic loading: + +```javascript +// Extension webpack.config.js +new ModuleFederationPlugin({ + name: 'my_extension', + filename: 'remoteEntry.[contenthash].js', + exposes: { + './index': './src/index.tsx', + }, + externals: { + '@apache-superset/core': 'superset', + }, + shared: { + react: { singleton: true }, + 'react-dom': { singleton: true }, + } +}) +``` + +This allows: +- **Independent builds**: Extensions compile separately from Superset +- **Shared dependencies**: Common libraries like React aren't duplicated +- **Dynamic loading**: Extensions load at runtime without rebuilding Superset +- **Version compatibility**: Extensions declare compatible core versions + +## Extension Lifecycle + +### 1. Registration +```typescript +// Extension registered with host +extensionManager.register({ + name: 'my-extension', + version: '1.0.0', + manifest: manifestData +}); +``` + +### 2. Activation +```typescript +// activate() called when extension loads +export function activate(context: ExtensionContext) { + // Register contributions + const disposables = []; + + // Add panel + disposables.push( + context.core.registerView('my-panel', MyPanel) + ); + + // Register command + disposables.push( + context.commands.registerCommand('my-command', { + execute: () => { /* ... */ } + }) + ); + + // Store for cleanup + context.subscriptions.push(...disposables); +} +``` + +### 3. Runtime +- Extension responds to events +- Provides UI components when requested +- Executes commands when triggered +- Accesses APIs as needed + +### 4. Deactivation +```typescript +// Automatic cleanup of registered items +export function deactivate() { + // context.subscriptions automatically disposed + // Additional cleanup if needed +} +``` + +## Contribution Types + +### Views +Extensions can add panels and UI components: + +```json +{ + "views": { + "sqllab.panels": [{ + "id": "my-panel", + "name": "My Panel", + "icon": "ToolOutlined" + }] + } +} +``` + +### Commands +Define executable actions: + +```json +{ + "commands": [{ + "command": "my-extension.run", + "title": "Run Analysis", + "icon": "PlayCircleOutlined" + }] +} +``` + +### Menus +Add items to existing menus: + +```json +{ + "menus": { + "sqllab.editor": { + "primary": [{ + "command": "my-extension.run", + "when": "editorHasSelection" + }] + } + } +} +``` + +### API Endpoints +Register backend REST endpoints: + +```python +from superset_core.api import rest_api + +@rest_api.route('/my-endpoint') +def my_endpoint(): + return {'data': 'value'} +``` + +## Security Model + +### Permissions +- Extensions run with user's permissions +- No elevation of privileges +- Access controlled by Superset's RBAC + +### Sandboxing +- Frontend code runs in browser context +- Backend code runs in Python process +- Future: Optional sandboxed execution + +### Validation +- Manifest validation on upload +- Signature verification (future) +- Dependency scanning + +## Performance Considerations + +### Lazy Loading +- Extensions load only when features are accessed +- Code splitting for large extensions +- Cached after first load + +### Bundle Optimization +- Tree shaking removes unused code +- Minification reduces size +- Compression for network transfer + +### Resource Management +- Automatic cleanup on deactivation +- Memory leak prevention +- Event listener management + +## Development vs Production + +### Development Mode +```python +# superset_config.py +ENABLE_EXTENSIONS = True +LOCAL_EXTENSIONS = ['/path/to/extension'] +``` +- Hot reloading +- Source maps +- Debug logging + +### Production Mode +- Optimized bundles +- Cached assets +- Performance monitoring + +## Future Enhancements + +### Planned Features +- Enhanced sandboxing +- Extension marketplace +- Inter-extension communication +- Theme contributions +- Chart type extensions + +### API Expansion +- Dashboard extensions +- Database connector API +- Security provider interface +- Workflow automation + +## Best Practices + +### Do's +- ✅ Use TypeScript for type safety +- ✅ Follow semantic versioning +- ✅ Handle errors gracefully +- ✅ Clean up resources properly +- ✅ Document your extension + +### Don'ts +- ❌ Access private APIs +- ❌ Modify global state directly +- ❌ Block the main thread +- ❌ Store sensitive data insecurely +- ❌ Assume API stability in 0.x versions + +## Learn More + +- [API Reference](../api/frontend) +- [Development Guide](../getting-started) +- [Security Guidelines](./security) +- [Performance Optimization](./performance) diff --git a/docs/developer_portal/cli/overview.md b/docs/developer_portal/cli/overview.md new file mode 100644 index 00000000000..6aa43dfcf4a --- /dev/null +++ b/docs/developer_portal/cli/overview.md @@ -0,0 +1,466 @@ + +--- +title: CLI Documentation +sidebar_position: 1 +hide_title: true +--- + +# Superset Extensions CLI + +The `apache-superset-extensions-cli` provides command-line tools for creating, developing, and packaging Superset extensions. + +## Installation + +```bash +pip install apache-superset-extensions-cli +``` + +## Commands + +### init + +Creates a new extension project with the standard folder structure. + +```bash +superset-extensions init [options] +``` + +**Options:** +- `--template