8ecb5d3a0c
* Add documentation code validation system - Create runnable example scripts in examples/api/ (19 files) - Add CodeSnippet component for extracting marked sections - Add raw-loader dependency for importing source files - Create sample retain-new.mdx showing new approach - Add README documenting coverage and gaps * Fix wheel glob expansion in test-doc-examples CI job * Fix CI issue * Fix wheel path - uv build outputs to repo root dist/ * Fix: use explicit shell expansion for wheel install * Fix: run cd in subshell so install runs from repo root * Add documentation code validation CI job - Use uv sync + uv run pattern (matches existing CI) - Add requests to test dependencies for cleanup scripts * Fix async API client usage in documents.py example * Fix main-methods.py: RecallResult and ReflectFact don't have weight attribute * Fix opinions.py: use actual API attributes instead of non-existent ones * Fix example scripts: remove non-existent API attributes - recall.py: remove .weight, fix entities iteration (dict not list) - retain.mjs: remove result.async check
82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
# API Documentation Examples
|
|
|
|
This directory contains runnable example scripts that serve as the source of truth for code samples in the documentation.
|
|
|
|
## How It Works
|
|
|
|
1. **Scripts are runnable** - Each file can be executed as a smoke test
|
|
2. **Markers define sections** - Code between `# [docs:section-name]` and `# [/docs:section-name]` markers is extracted
|
|
3. **Docs import at build time** - MDX files use `raw-loader` to import scripts, then `CodeSnippet` extracts marked sections
|
|
|
|
## File Structure
|
|
|
|
| File | Documentation | Description |
|
|
|------|---------------|-------------|
|
|
| `quickstart.py/mjs/sh` | quickstart.md | Getting started examples |
|
|
| `retain.py/mjs/sh` | retain.md | Memory ingestion examples |
|
|
| `recall.py/mjs/sh` | recall.md | Memory retrieval examples |
|
|
| `reflect.py/mjs/sh` | reflect.md | AI reflection examples |
|
|
| `memory-banks.py/mjs` | memory-banks.md | Bank management examples |
|
|
| `documents.py/mjs` | documents.md | Document CRUD examples |
|
|
| `opinions.py` | opinions.md | Opinion management examples |
|
|
| `main-methods.py` | main-methods.md | Core method examples |
|
|
| `cli-reference.sh` | cli.md | CLI command examples |
|
|
|
|
## Running Examples
|
|
|
|
```bash
|
|
# Run all Python examples
|
|
for f in *.py; do python "$f"; done
|
|
|
|
# Run all Node.js examples
|
|
for f in *.mjs; do node "$f"; done
|
|
|
|
# Run all CLI examples
|
|
for f in *.sh; do bash "$f"; done
|
|
```
|
|
|
|
Requires a running Hindsight server at `http://localhost:8888` (or set `HINDSIGHT_API_URL`).
|
|
|
|
## What's NOT Covered
|
|
|
|
### 1. OpenAPI Auto-Generated Docs (`/api-reference/*`)
|
|
|
|
These pages are generated directly from the OpenAPI specification. The spec itself is the source of truth, and the generated docs reflect it automatically. No manual code examples to validate.
|
|
|
|
### 2. Interactive CLI Commands
|
|
|
|
| Command | Reason |
|
|
|---------|--------|
|
|
| `hindsight configure` | Requires interactive user input (prompts for API URL, credentials) |
|
|
| `hindsight configure --show` | Displays sensitive configuration, not suitable for automated tests |
|
|
|
|
### 3. Installation/Setup Instructions
|
|
|
|
Documentation sections covering `pip install`, `npm install`, or system setup are instructions, not executable code samples. These are validated by the CI environment setup itself.
|
|
|
|
### 4. Error Handling Examples
|
|
|
|
Some docs show error responses (e.g., "what happens when bank doesn't exist"). These require intentionally broken states that would fail smoke tests. Error behavior is covered by unit tests instead.
|
|
|
|
## Adding New Examples
|
|
|
|
1. Create or edit the appropriate script file
|
|
2. Add markers around the new code section:
|
|
```python
|
|
# [docs:my-new-section]
|
|
client.some_method(...)
|
|
# [/docs:my-new-section]
|
|
```
|
|
3. Reference in the MDX file:
|
|
```mdx
|
|
import myScript from '!!raw-loader!@site/examples/api/my-script.py';
|
|
<CodeSnippet code={myScript} section="my-new-section" language="python" />
|
|
```
|
|
4. Run the script locally to verify it works
|
|
|
|
## Marker Format
|
|
|
|
- **Python/Bash**: `# [docs:section-name]` / `# [/docs:section-name]`
|
|
- **JavaScript**: `// [docs:section-name]` / `// [/docs:section-name]`
|
|
|
|
Section names should be kebab-case and descriptive (e.g., `retain-with-context`, `recall-basic`).
|