@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/code-documenter/references/documentation-systems.md

@@ -0,0 +1,336 @@
+# Documentation Systems & Infrastructure
+
+> Reference for: Code Documenter
+> Load when: Building documentation sites, static generators, multi-version docs, search systems
+
+## 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 |