doc-render-sdk 0.0.1

package/README.md

@@ -0,0 +1,321 @@
+# 文档渲染SDK
+
+一个专门用于渲染组件文档站点的SDK，从原有的doc目录抽象而来。
+
+## 特性
+
+- 🎨 **主题化设计** - 支持自定义主题和样式
+- 📱 **响应式布局** - 适配各种屏幕尺寸
+- 🔧 **组件化架构** - 高度可复用的文档组件
+- 📖 **Demo展示** - 支持代码预览、实时运行、代码折叠
+- 📋 **API文档** - 结构化的API参数文档
+- 🚀 **热更新** - 开发时支持热更新
+- 🎯 **插件系统** - 支持自定义插件扩展功能
+- 📦 **零配置** - 开箱即用，同时支持深度定制
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install doc-sdk
+```
+
+### 基本使用
+
+```javascript
+import DocSDK from 'doc-sdk';
+
+const docSdk = new DocSDK({
+  title: '我的组件库文档',
+  theme: 'default',
+  components: {
+    'my-component': {
+      label: '我的组件',
+      demos: [
+        {
+          title: '基础用法',
+          desc: '组件的基础使用方式',
+          source: 'basic'
+        }
+      ],
+      apis: [
+        {
+          title: 'MyComponent',
+          apiKey: 'my-component'
+        }
+      ]
+    }
+  }
+});
+
+docSdk.render('#app');
+```
+
+## 架构设计
+
+### 核心模块
+
+- **DocRenderer** - 文档渲染器核心
+- **ConfigManager** - 配置管理器
+- **ComponentRegistry** - 组件注册表
+- **ThemeManager** - 主题管理器
+- **PluginManager** - 插件管理器
+- **RouterManager** - 路由管理器
+
+### 组件系统
+
+- **Layout** - 布局组件
+- **Navigation** - 导航组件
+- **Demo** - 演示组件
+- **ApiDoc** - API文档组件
+- **CodeBlock** - 代码块组件
+- **Search** - 搜索组件
+
+## 目录结构
+
+```
+doc-sdk/
+├── src/
+│   ├── core/           # 核心模块
+│   │   ├── DocRenderer.js      # 文档渲染器
+│   │   ├── ConfigManager.js    # 配置管理器
+│   │   ├── ComponentRegistry.js # 组件注册表
+│   │   ├── ThemeManager.js     # 主题管理器
+│   │   ├── PluginManager.js    # 插件管理器
+│   │   └── RouterManager.js    # 路由管理器
+│   ├── components/     # 文档组件
+│   │   ├── Layout.jsx          # 主布局组件
+│   │   ├── Navigation.jsx      # 导航组件
+│   │   ├── Header.jsx          # 头部组件
+│   │   ├── Content.jsx         # 内容组件
+│   │   ├── Demo.jsx            # Demo展示组件
+│   │   ├── ApiDoc.jsx          # API文档组件
+│   │   ├── CodeBlock.jsx       # 代码块组件
+│   │   ├── Search.jsx          # 搜索组件
+│   │   ├── Home.jsx            # 首页组件
+│   │   └── Footer.jsx          # 页脚组件
+│   ├── themes/         # 主题文件
+│   │   └── default.js          # 默认主题
+│   ├── config/         # 配置文件
+│   │   └── default.js          # 默认配置
+│   ├── utils/          # 工具函数
+│   │   └── index.js            # 工具函数集合
+│   └── index.js        # 入口文件
+├── bin/                # CLI工具
+│   └── doc-sdk.js      # 命令行工具
+├── tools/              # 构建工具
+│   └── migrate.js      # 迁移工具
+├── examples/           # 示例项目
+│   ├── index.html      # 示例HTML
+│   └── index.js        # 示例配置
+├── lib/                # CommonJS构建输出
+├── es/                 # ES模块构建输出
+├── docs-new/           # 迁移示例
+└── README.md           # 说明文档
+```
+
+## 🎯 设计理念
+
+### 核心原则
+
+1. **组件化架构** - 高度模块化，每个功能都是独立的组件
+2. **配置驱动** - 通过配置文件控制所有行为，减少硬编码
+3. **主题化设计** - 支持深度定制，满足不同项目需求
+4. **插件扩展** - 提供插件系统，支持功能扩展
+5. **开发友好** - 提供完整的开发工具链和迁移工具
+
+### 技术栈
+
+- **React** - 组件渲染
+- **Webpack** - 模块打包
+- **Babel** - 代码转换
+- **Less/CSS** - 样式处理
+- **Highlight.js** - 代码高亮
+- **Mini-event** - 事件系统
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+npm install doc-sdk
+```
+
+### 基本使用
+
+```javascript
+import DocSDK from 'doc-sdk';
+
+const docSdk = new DocSDK({
+  title: '我的组件库',
+  components: {
+    'button': {
+      label: 'Button 按钮',
+      demos: [
+        {
+          title: '基础用法',
+          desc: '最简单的用法',
+          source: 'basic'
+        }
+      ],
+      apis: [
+        {
+          title: 'Button',
+          apiKey: 'Button'
+        }
+      ]
+    }
+  }
+});
+
+docSdk.render('#app');
+```
+
+### CLI 工具
+
+```bash
+# 创建新项目
+npx doc-sdk create my-docs
+
+# 启动开发服务器
+npx doc-sdk dev
+
+# 构建项目
+npx doc-sdk build
+
+# 迁移旧项目
+npx doc-sdk migrate --source ./doc --target ./docs-new
+```
+
+## 📚 详细文档
+
+### 配置选项
+
+```javascript
+const config = {
+  // 基本信息
+  title: 'Documentation',
+  description: 'Component Documentation Site',
+  version: '1.0.0',
+
+  // 主题配置
+  theme: {
+    name: 'default',
+    colors: {
+      primary: '#1890ff'
+    }
+  },
+
+  // 布局配置
+  layout: {
+    type: 'sidebar', // sidebar, top, mixed
+    sidebar: {
+      width: 280,
+      collapsible: true
+    }
+  },
+
+  // 组件配置
+  components: {
+    'component-name': {
+      label: '组件名称',
+      description: '组件描述',
+      demos: [...],
+      apis: [...]
+    }
+  },
+
+  // 搜索配置
+  search: {
+    enabled: true,
+    placeholder: '搜索...'
+  }
+};
+```
+
+### 组件注册
+
+```javascript
+// 注册Demo组件
+window.__DOC_SDK_DEMOS__ = {
+  'component-name': {
+    'demo-name': DemoComponent
+  }
+};
+
+// 注册Demo代码
+window.__DOC_SDK_DEMO_CODES__ = {
+  'component-name': {
+    'demo-name': 'const Demo = () => <div>Hello</div>;'
+  }
+};
+
+// 注册API文档
+window.__DOC_SDK_APIS__ = {
+  'component-name': {
+    'api-name': [
+      {
+        param: 'prop',
+        type: 'string',
+        desc: '属性描述',
+        default: '',
+        required: false
+      }
+    ]
+  }
+};
+```
+
+## 🔧 高级功能
+
+### 自定义主题
+
+```javascript
+const customTheme = {
+  name: 'custom',
+  colors: {
+    primary: '#ff6b6b',
+    success: '#51cf66',
+    warning: '#ffd43b',
+    error: '#ff6b6b'
+  },
+  typography: {
+    fontFamily: 'Inter, sans-serif'
+  },
+  components: {
+    demo: `
+      .doc-demo {
+        border-radius: 12px;
+        box-shadow: 0 4px 12px rgba(0,0,0,0.1);
+      }
+    `
+  }
+};
+
+const docSdk = new DocSDK({
+  theme: customTheme
+});
+```
+
+### 插件开发
+
+```javascript
+const myPlugin = {
+  name: 'my-plugin',
+  version: '1.0.0',
+  install(context) {
+    // 添加钩子
+    context.hooks.add('beforeRender', () => {
+      console.log('Before render');
+    });
+
+    // 监听事件
+    context.events.on('routeChange', (route) => {
+      console.log('Route changed:', route);
+    });
+  }
+};
+
+docSdk.use(myPlugin);
+```

package/bin/doc-sdk.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+
+/**
+ * Doc SDK CLI 工具
+ */
+
+const { program } = require('commander');
+const path = require('path');
+const fs = require('fs');
+const { spawn } = require('child_process');
+
+program
+  .name('doc-sdk')
+  .description('Doc SDK CLI - 文档站点构建工具')
+  .version('1.0.0');
+
+// 创建新项目
+program
+  .command('create <project-name>')
+  .description('创建新的文档项目')
+  .option('-t, --template <template>', '使用模板', 'default')
+  .action(async (projectName, options) => {
+    console.log(`🚀 创建文档项目: ${projectName}`);
+    
+    const projectDir = path.resolve(projectName);
+    
+    if (fs.existsSync(projectDir)) {
+      console.error(`❌ 目录已存在: ${projectDir}`);
+      process.exit(1);
+    }
+
+    try {
+      await createProject(projectDir, options.template);
+      console.log('✅ 项目创建成功!');
+      console.log(`📁 项目目录: ${projectDir}`);
+      console.log('\n下一步:');
+      console.log(`  cd ${projectName}`);
+      console.log('  npm install');
+      console.log('  npm run dev');
+    } catch (error) {
+      console.error('❌ 创建失败:', error.message);
+      process.exit(1);
+    }
+  });
+
+// 开发服务器
+program
+  .command('dev')
+  .description('启动开发服务器')
+  .option('-p, --port <port>', '端口号', '8080')
+  .option('-h, --host <host>', '主机地址', 'localhost')
+  .action((options) => {
+    console.log('🚀 启动开发服务器...');
+    
+    const configPath = findConfig();
+    if (!configPath) {
+      console.error('❌ 未找到配置文件');
+      process.exit(1);
+    }
+
+    startDevServer(configPath, options);
+  });
+
+// 构建项目
+program
+  .command('build')
+  .description('构建文档站点')
+  .option('-o, --output <dir>', '输出目录', 'dist')
+  .action((options) => {
+    console.log('📦 构建文档站点...');
+    
+    const configPath = findConfig();
+    if (!configPath) {
+      console.error('❌ 未找到配置文件');
+      process.exit(1);
+    }
+
+    buildProject(configPath, options);
+  });
+
+
+// 预览构建结果
+program
+  .command('preview')
+  .description('预览构建结果')
+  .option('-p, --port <port>', '端口号', '3000')
+  .option('-d, --dir <dir>', '构建目录', 'dist')
+  .action((options) => {
+    console.log('👀 预览构建结果...');
+    previewBuild(options);
+  });
+
+program.parse();
+
+/**
+ * 创建新项目
+ */
+async function createProject(projectDir, template) {
+  // 创建项目目录
+  fs.mkdirSync(projectDir, { recursive: true });
+
+  // 生成package.json
+  const packageJson = {
+    name: path.basename(projectDir),
+    version: '1.0.0',
+    description: 'Documentation site built with Doc SDK',
+    main: 'index.js',
+    scripts: {
+      dev: 'doc-sdk dev',
+      build: 'doc-sdk build',
+      preview: 'doc-sdk preview'
+    },
+    dependencies: {
+      'doc-sdk': '^1.0.0'
+    },
+    devDependencies: {
+      webpack: '^5.88.0',
+      'webpack-cli': '^5.1.0',
+      'webpack-dev-server': '^4.15.0'
+    }
+  };
+
+  fs.writeFileSync(
+    path.join(projectDir, 'package.json'),
+    JSON.stringify(packageJson, null, 2)
+  );
+
+  // 生成配置文件
+  const config = {
+    title: 'My Documentation',
+    description: 'Component documentation built with Doc SDK',
+    version: '1.0.0',
+    components: {
+      'example': {
+        label: 'Example Component',
+        description: 'An example component to get you started',
+        demos: [
+          {
+            title: 'Basic Usage',
+            desc: 'Basic usage of the component',
+            source: 'basic'
+          }
+        ],
+        apis: [
+          {
+            title: 'Example',
+            apiKey: 'Example'
+          }
+        ]
+      }
+    }
+  };
+
+  fs.writeFileSync(
+    path.join(projectDir, 'doc.config.js'),
+    `export default ${JSON.stringify(config, null, 2)};`
+  );
+
+  // 生成入口文件
+  const indexJs = `import DocSDK from 'doc-sdk';
+import config from './doc.config.js';
+
+// 注册示例组件
+const ExampleComponent = () => {
+  return (
+    <div style={{ padding: '20px' }}>
+      <h3>Example Component</h3>
+      <p>This is an example component.</p>
+    </div>
+  );
+};
+
+// 注册全局组件
+window.__DOC_SDK_DEMOS__ = {
+  'example': {
+    'basic': ExampleComponent
+  }
+};
+
+window.__DOC_SDK_DEMO_CODES__ = {
+  'example': {
+    'basic': \`const ExampleComponent = () => {
+  return (
+    <div style={{ padding: '20px' }}>
+      <h3>Example Component</h3>
+      <p>This is an example component.</p>
+    </div>
+  );
+};\`
+  }
+};
+
+window.__DOC_SDK_APIS__ = {
+  'example': {
+    'Example': [
+      {
+        param: 'children',
+        type: 'ReactNode',
+        desc: 'The content of the component',
+        option: '',
+        default: '',
+        required: false
+      }
+    ]
+  }
+};
+
+const docSdk = new DocSDK(config);
+docSdk.render('#app');
+`;
+
+  fs.writeFileSync(path.join(projectDir, 'index.js'), indexJs);
+
+  // 生成HTML文件
+  const indexHtml = `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My Documentation</title>
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css">
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
+</head>
+<body>
+  <div id="app"></div>
+</body>
+</html>`;
+
+  fs.writeFileSync(path.join(projectDir, 'index.html'), indexHtml);
+
+  // 生成README
+  const readme = `# ${path.basename(projectDir)}
+
+Documentation site built with Doc SDK.
+
+## Getting Started
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Commands
+
+- \`npm run dev\` - Start development server
+- \`npm run build\` - Build for production
+- \`npm run preview\` - Preview build
+
+## Documentation
+
+- [Doc SDK Documentation](https://github.com/your-org/doc-sdk)
+`;
+
+  fs.writeFileSync(path.join(projectDir, 'README.md'), readme);
+}
+
+/**
+ * 查找配置文件
+ */
+function findConfig() {
+  const configFiles = [
+    'doc.config.js',
+    'doc.config.json',
+    'docs.config.js',
+    'docs.config.json'
+  ];
+
+  for (const file of configFiles) {
+    if (fs.existsSync(file)) {
+      return path.resolve(file);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 启动开发服务器
+ */
+function startDevServer(configPath, options) {
+  const webpackConfig = generateWebpackConfig(configPath, 'development', options);
+  const configFile = path.join(__dirname, '../webpack.temp.js');
+  
+  fs.writeFileSync(configFile, `module.exports = ${JSON.stringify(webpackConfig, null, 2)};`);
+  
+  const child = spawn('npx', ['webpack', 'serve', '--config', configFile], {
+    stdio: 'inherit',
+    shell: true
+  });
+
+  child.on('close', (code) => {
+    fs.unlinkSync(configFile);
+    process.exit(code);
+  });
+}
+
+/**
+ * 构建项目
+ */
+function buildProject(configPath, options) {
+  const webpackConfig = generateWebpackConfig(configPath, 'production', options);
+  const configFile = path.join(__dirname, '../webpack.temp.js');
+  
+  fs.writeFileSync(configFile, `module.exports = ${JSON.stringify(webpackConfig, null, 2)};`);
+  
+  const child = spawn('npx', ['webpack', '--config', configFile], {
+    stdio: 'inherit',
+    shell: true
+  });
+
+  child.on('close', (code) => {
+    fs.unlinkSync(configFile);
+    if (code === 0) {
+      console.log('✅ 构建完成!');
+    }
+    process.exit(code);
+  });
+}
+
+/**
+ * 预览构建结果
+ */
+function previewBuild(options) {
+  const express = require('express');
+  const app = express();
+  
+  app.use(express.static(options.dir));
+  
+  app.listen(options.port, () => {
+    console.log(`📖 预览地址: http://localhost:${options.port}`);
+  });
+}
+
+/**
+ * 生成webpack配置
+ */
+function generateWebpackConfig(configPath, mode, options) {
+  // 这里应该生成完整的webpack配置
+  // 简化版本，实际使用时需要完善
+  return {
+    mode,
+    entry: './index.js',
+    output: {
+      path: path.resolve(options.output || 'dist'),
+      filename: 'bundle.js'
+    }
+  };
+}