mirror of
https://github.com/apache/superset.git
synced 2026-04-20 00:24:38 +00:00
116 lines
3.2 KiB
Markdown
116 lines
3.2 KiB
Markdown
# Developer Portal Documentation Instructions
|
||
|
||
## Core Principle: Stories Are the Single Source of Truth
|
||
|
||
When working on the Storybook-to-MDX documentation system:
|
||
|
||
**ALWAYS fix the story first. NEVER add workarounds to the generator.**
|
||
|
||
## Why This Matters
|
||
|
||
The generator (`scripts/generate-superset-components.mjs`) should be lightweight - it extracts data from stories and passes it through. When you add special cases to the generator:
|
||
- It becomes harder to maintain
|
||
- Stories diverge from their docs representation
|
||
- Future stories need to know about generator quirks
|
||
|
||
When you fix stories to match the expected patterns:
|
||
- Stories work identically in Storybook and Docs
|
||
- The generator stays simple and predictable
|
||
- Patterns are consistent and learnable
|
||
|
||
## Story Patterns for Docs Generation
|
||
|
||
### Required Structure
|
||
```tsx
|
||
// Use inline export default (NOT const meta = ...; export default meta)
|
||
export default {
|
||
title: 'Components/MyComponent',
|
||
component: MyComponent,
|
||
};
|
||
|
||
// Name interactive stories with Interactive prefix
|
||
export const InteractiveMyComponent: Story = {
|
||
args: {
|
||
// Default prop values
|
||
},
|
||
argTypes: {
|
||
// Control definitions - MUST be at story level, not meta level
|
||
propName: {
|
||
control: { type: 'select' },
|
||
options: ['a', 'b', 'c'],
|
||
description: 'What this prop does',
|
||
},
|
||
},
|
||
};
|
||
```
|
||
|
||
### For Components with Variants (size × style grids)
|
||
```tsx
|
||
const sizes = ['small', 'medium', 'large'];
|
||
const variants = ['primary', 'secondary', 'danger'];
|
||
|
||
InteractiveButton.parameters = {
|
||
docs: {
|
||
gallery: {
|
||
component: 'Button',
|
||
sizes,
|
||
styles: variants,
|
||
sizeProp: 'size',
|
||
styleProp: 'variant',
|
||
},
|
||
},
|
||
};
|
||
```
|
||
|
||
### For Components Requiring Children
|
||
```tsx
|
||
InteractiveIconTooltip.parameters = {
|
||
docs: {
|
||
// Component descriptors with dot notation for nested components
|
||
sampleChildren: [{ component: 'Icons.InfoCircleOutlined', props: { iconSize: 'l' } }],
|
||
},
|
||
};
|
||
```
|
||
|
||
### For Custom Live Code Examples
|
||
```tsx
|
||
InteractiveMyComponent.parameters = {
|
||
docs: {
|
||
liveExample: `function Demo() {
|
||
return <MyComponent prop="value">Content</MyComponent>;
|
||
}`,
|
||
},
|
||
};
|
||
```
|
||
|
||
### For Complex Props (objects, arrays)
|
||
```tsx
|
||
InteractiveMenu.parameters = {
|
||
docs: {
|
||
staticProps: {
|
||
items: [
|
||
{ key: '1', label: 'Item 1' },
|
||
{ key: '2', label: 'Item 2' },
|
||
],
|
||
},
|
||
},
|
||
};
|
||
```
|
||
|
||
## Common Issues and How to Fix Them (in the Story)
|
||
|
||
| Issue | Wrong Approach | Right Approach |
|
||
|-------|---------------|----------------|
|
||
| Component not generated | Add pattern to generator | Change story to use inline `export default` |
|
||
| Control shows as text instead of select | Add special case in generator | Add `argTypes` with `control: { type: 'select' }` |
|
||
| Missing children/content | Modify StorybookWrapper | Add `parameters.docs.sampleChildren` |
|
||
| Gallery not showing | Add to generator output | Add `parameters.docs.gallery` config |
|
||
| Wrong live example | Hardcode in generator | Add `parameters.docs.liveExample` |
|
||
|
||
## Files
|
||
|
||
- **Generator**: `docs/scripts/generate-superset-components.mjs`
|
||
- **Wrapper**: `docs/src/components/StorybookWrapper.jsx`
|
||
- **Output**: `docs/developer_docs/components/`
|
||
- **Stories**: `superset-frontend/packages/superset-ui-core/src/components/*/`
|