aigroup-workflow 2.1.2 → 2.2.1

package/skills/code-documenter/references/documentation-systems.md

@@ -1,333 +0,0 @@
-# Documentation Systems & Infrastructure
-
-## Static Site Generators
-
-### Docusaurus (Meta)
-
-```bash
-# Setup
-npx create-docusaurus@latest docs classic
-cd docs && npm start
-
-# Structure
-docs/
-├── docs/           # Documentation pages
-├── blog/           # Blog posts
-├── src/
-│   └── pages/      # Custom pages
-└── docusaurus.config.js
-```
-
-**docusaurus.config.js:**
-```javascript
-module.exports = {
-  title: 'My API',
-  tagline: 'Build amazing things',
-  url: 'https://docs.example.com',
-  baseUrl: '/',
-
-  themeConfig: {
-    navbar: {
-      items: [
-        {to: '/docs/intro', label: 'Docs', position: 'left'},
-        {to: '/api', label: 'API', position: 'left'},
-      ],
-    },
-
-    // Algolia search
-    algolia: {
-      apiKey: 'YOUR_API_KEY',
-      indexName: 'your_index',
-      contextualSearch: true,
-    },
-
-    prism: {
-      theme: lightCodeTheme,
-      darkTheme: darkCodeTheme,
-      additionalLanguages: ['python', 'rust'],
-    },
-  },
-};
-```
-
-### MkDocs (Python)
-
-```yaml
-# mkdocs.yml
-site_name: My API Documentation
-theme:
-  name: material
-  features:
-    - navigation.tabs
-    - navigation.sections
-    - toc.integrate
-    - search.suggest
-    - search.highlight
-  palette:
-    - scheme: default
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-    - scheme: slate
-      toggle:
-        icon: material/brightness-4
-        name: Switch to light mode
-
-plugins:
-  - search
-  - mkdocstrings:
-      handlers:
-        python:
-          options:
-            show_source: true
-  - git-revision-date-localized
-
-markdown_extensions:
-  - pymdownx.highlight
-  - pymdownx.superfences
-  - admonition
-  - codehilite
-
-nav:
-  - Home: index.md
-  - Getting Started: getting-started.md
-  - API Reference: api/
-```
-
-### VitePress (Vue)
-
-```typescript
-// .vitepress/config.ts
-export default defineConfig({
-  title: 'API Docs',
-  description: 'Developer documentation',
-
-  themeConfig: {
-    nav: [
-      { text: 'Guide', link: '/guide/' },
-      { text: 'API', link: '/api/' },
-    ],
-
-    sidebar: {
-      '/guide/': [
-        {
-          text: 'Introduction',
-          items: [
-            { text: 'Getting Started', link: '/guide/getting-started' },
-            { text: 'Configuration', link: '/guide/config' },
-          ],
-        },
-      ],
-    },
-
-    search: {
-      provider: 'local',
-    },
-
-    editLink: {
-      pattern: 'https://github.com/user/repo/edit/main/docs/:path',
-    },
-  },
-});
-```
-
-## Multi-Version Documentation
-
-### Version Switcher
-
-```javascript
-// Docusaurus versions
-{
-  versions: {
-    current: {
-      label: '2.0 (Next)',
-      path: 'next',
-    },
-  },
-  onlyIncludeVersions: ['current', '1.5', '1.4'],
-}
-```
-
-### Migration Guides
-
-```markdown
-# Migration Guide: v1 to v2
-
-## Breaking Changes
-
-### Authentication
-**v1:**
-```python
-client.authenticate(api_key)
-```
-
-**v2:**
-```python
-client = Client(api_key=api_key)  # Pass in constructor
-```
-
-### Renamed Methods
-| v1 | v2 | Notes |
-|----|----|----- |
-| `get_user()` | `fetch_user()` | Async now |
-| `delete_user()` | `remove_user()` | Returns Promise |
-
-## Deprecation Timeline
-- v1.x: Supported until Dec 2025
-- v2.0: Released Jan 2025
-- v2.1: Current (June 2025)
-```
-
-## Search Implementation
-
-### Algolia DocSearch
-
-```html
-<!-- Add to theme -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />
-
-<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>
-<script>
-  docsearch({
-    appId: 'YOUR_APP_ID',
-    apiKey: 'YOUR_API_KEY',
-    indexName: 'your_index',
-    container: '#docsearch',
-  });
-</script>
-```
-
-### Local Search (Lunr.js)
-
-```javascript
-const idx = lunr(function() {
-  this.ref('id');
-  this.field('title', { boost: 10 });
-  this.field('content');
-
-  documents.forEach(doc => this.add(doc));
-});
-
-// Search
-const results = idx.search('authentication');
-```
-
-## Documentation Testing
-
-### Link Checking
-
-```bash
-# linkcheck (Python)
-pip install linkchecker
-linkchecker http://localhost:3000/docs
-
-# broken-link-checker (Node)
-npm install -g broken-link-checker
-blc http://localhost:3000 -ro
-```
-
-### Code Example Testing
-
-```python
-# doctest for Python examples
-"""
->>> add(2, 3)
-5
->>> add(-1, 1)
-0
-"""
-
-# Run tests
-python -m doctest -v docs/*.md
-```
-
-```javascript
-// Jest for TypeScript examples
-// Extract code blocks and test
-import { runExamples } from './test-docs';
-
-test('API examples work', async () => {
-  const examples = extractExamples('./docs/api.md');
-  await expect(runExamples(examples)).resolves.toBeTruthy();
-});
-```
-
-## Performance Optimization
-
-### Build Optimization
-
-```javascript
-// Webpack/Vite config
-export default {
-  build: {
-    rollupOptions: {
-      output: {
-        manualChunks: {
-          'vendor': ['react', 'react-dom'],
-        },
-      },
-    },
-  },
-
-  optimizeDeps: {
-    include: ['prismjs'],
-  },
-};
-```
-
-### CDN & Caching
-
-```nginx
-# nginx.conf
-location /docs {
-  expires 1y;
-  add_header Cache-Control "public, immutable";
-}
-
-location ~* \.(html)$ {
-  expires 1h;
-  add_header Cache-Control "public, must-revalidate";
-}
-```
-
-## Analytics Integration
-
-### Google Analytics
-
-```javascript
-// Docusaurus
-gtag: {
-  trackingID: 'G-XXXXXXXXXX',
-  anonymizeIP: true,
-},
-```
-
-### Custom Analytics
-
-```javascript
-// Track search queries
-function trackSearch(query, results) {
-  analytics.track('docs_search', {
-    query,
-    resultCount: results.length,
-    timestamp: new Date(),
-  });
-}
-```
-
-## Quick Reference
-
-| Tool | Best For | Tech Stack |
-|------|----------|-----------|
-| Docusaurus | React projects, versioning | React, MDX |
-| MkDocs | Python projects, simple setup | Python, Jinja2 |
-| VitePress | Vue projects, fast builds | Vue, Vite |
-| Nextra | Next.js integration | React, Next.js |
-| Mintlify | Modern UI, AI search | React |
-
-| Search Solution | Cost | Features |
-|----------------|------|----------|
-| Algolia DocSearch | Free (OSS) | Fast, typo-tolerant |
-| Local (Lunr.js) | Free | Offline, no server |
-| Typesense | Free (self-host) | Privacy-focused |
-| Meilisearch | Free (self-host) | Fast, relevance |