cloud-ide-docs

Centralized documentation package for Cloud IDE components, projects, and user-defined docs. Supports manifest-based discovery, runtime registration, component control API, and doc-driven events (Google-style interactive docs).

Overview

• Manifest: Build-time docs (component, project, guides) loaded from docs-manifest.json
• User-defined docs: Docs created by users, stored in user storage, registered at runtime via registerDocument()
• Component control: Drive or inspect components via CideDocControllable and CIDE_DOCS_COMPONENT_CONTROL token

Features

• Get doc by ID: getDocumentById(id)
• Load by documentId in parent component
• Pass context: documentContext for live state
• Doc actions/events: buttons in doc emit DocActionEvent to communicate with components
• Control API: getDocState, setDocState, executeDocAction
• Export manifest: exportManifest() for external tools/AI
• Versioning, i18n, deprecation, accessibility (optional)
• User-defined docs

Quick Start

import { DocsRegistryService } from 'cloud-ide-docs';
import manifest from './assets/docs-manifest.json';

// In app init
constructor(private docsRegistry: DocsRegistryService) {
  this.docsRegistry.loadManifest(manifest);
}

// In parent component
const doc = this.docsRegistry.getDocumentById(this.documentId);
// Pass doc + optional documentContext to doc-viewer

How to Use

Add component doc (manifest)

1. Add or change the Angular component in its library
2. Run npm run build-docs-manifest
3. The script scans *.component.ts, parses @Component and JSDoc, writes manifest

Add component doc (runtime)

this.docsRegistry.registerDocument({
  type: 'component',
  id: 'my-component',
  selector: 'app-my',
  name: 'MyComponent',
  project: 'my-lib',
  description: '...',
});

Add user-defined doc

1. User creates doc via UI; save to storage (DB, API, local storage)
2. On app init, load user docs and call registerDocument() for each

Load doc in parent

@Input() documentId!: string;

ngOnInit() {
  const doc = this.docsRegistry.getDocumentById(this.documentId);
  // Pass to doc-viewer: [doc]="doc" [documentContext]="context"
}

Pass context and handle actions

• Parent passes documentContext (e.g. from getDocState()) to doc-viewer
• Doc schema supports actions; viewer emits DocActionEvent on click
• Handler routes events to component control API or app actions

Add long-form content

• Add markdown under content/ (e.g. content/guides/getting-started.md)
• Reference via manifest contentUrl or registerDocument({ contentUrl: '...' })

How AI Can Add Docs

• Manifest: Edit docs-manifest.json or JSDoc in component files; run npm run build-docs-manifest
• Content: Create/edit markdown in content/; reference via contentUrl or registerDocument()
• User-defined: Call DocsRegistryService.registerDocument(doc) with valid DocEntry
• Schema: See minimal example below. Required: id, type. For component: selector, name, project

Minimal DocEntry example

{
  "type": "standalone",
  "id": "my-guide",
  "title": "My Guide",
  "description": "A short guide",
  "content": "# Markdown content here"
}

Routine

• Run npm run build-docs-manifest and validate output
• Suggest JSDoc for new components (@description above @Component)

Routine Actions

| When | Action | |------|--------| | Every build | Run build-docs-manifest; optionally validate; --strict fails if coverage drops | | Every release | Generate changelog; update versioned manifest; deploy to /docs/v1.2.0/ | | New component | Add JSDoc; re-run manifest; optionally add content/{id}.md | | Deprecation | Set deprecated: true, deprecationMessage, replacementId; add migration guide | | Doc coverage | Run manifest with coverage report; fix missing docs | | User-defined | On app init, load from storage and registerDocument() each |

API Reference

DocsRegistryService

• loadManifest(manifest: DocsManifest): void
• registerDocument(doc: DocEntry): void
• registerComponent(meta: ComponentDocEntry): void
• registerProject(meta: ProjectDocEntry): void
• getDocumentById(id: string, options?: GetDocumentByIdOptions): DocEntry | null
• getComponentBySelector(selector: string): ComponentDocEntry | null
• getProjects(): ProjectDocEntry[]
• getComponents(): ComponentDocEntry[]
• exportManifest(): DocsManifest

CideDocControllable (implement on components)

• getDocState(): unknown
• setDocState?(state: unknown): void
• executeDocAction?(actionId: string, payload?: unknown): unknown

CIDE_DOCS_COMPONENT_CONTROL

Provide in host app with adapter that resolves components and forwards getDocState, setDocState, executeDocAction.

Manifest Schema

• schemaVersion: string (e.g. "1.0")
• projects: ProjectDocEntry[]
• components: ComponentDocEntry[]
• standalone: StandaloneDocEntry[]

Each doc has id, type. Component: selector, name, project. Optional: description, inputs, outputs, methods, actions, version, deprecated, i18n, etc.

Troubleshooting

| Issue | Fix | |-------|-----| | Doc not found | Check id; ensure manifest loaded or registerDocument called | | Duplicate id | Use unique ids; later registration overwrites | | Manifest load failure | Ensure path correct; check JSON valid | | --strict fails | Add JSDoc @description to components |