API Reference
programmatic access to PhenoDocs functionality
Python API
HubGenerator
Main class for generating federation hubs.
python
from docs_engine.hub.generator import HubGenerator
from pathlib import Path1
2
2
Constructor
python
HubGenerator(hub_dir: Path, projects: dict[str, str]) -> HubGenerator1
Parameters:
hub_dir— Output directory for the hubprojects— Dict mapping project names to doc paths
Example:
python
gen = HubGenerator(
hub_dir=Path("./phenodocs"),
projects={
"thegent": "/workspace/thegent/docs",
"pheno-sdk": "/workspace/pheno-sdk/docs"
}
)1
2
3
4
5
6
7
2
3
4
5
6
7
Methods
generate()
python
def generate(self) -> None1
Write hub files. Idempotent — safe to call multiple times.
Creates:
index.md— Landing page.vitepress/config.ts— VitePress configpackage.json— Dependencies
Example:
python
gen.generate()
print("Hub generated successfully!")1
2
2
CLI Commands
docs hub
bash
docs hub [OPTIONS]1
Options:
--hub-dir PATH— Hub output directory (default: "../docs-hub")
Example:
bash
docs hub --hub-dir ./phenodocs1
MCP Tools
thegent_doc_hub_generate
Generate or regenerate the VitePress federation hub.
json
{
"name": "thegent_doc_hub_generate",
"arguments": {
"hub_dir": "../phenodocs"
}
}1
2
3
4
5
6
2
3
4
5
6
Configuration Files
package.json
json
{
"name": "phenodocs",
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "vitepress dev",
"build": "vitepress build",
"preview": "vitepress preview"
},
"devDependencies": {
"vitepress": "^1.0.0"
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
.vitepress/config.ts
typescript
import { defineConfig } from 'vitepress'
export default defineConfig({
title: 'PhenoDocs',
description: 'Federation hub for all project documentation',
themeConfig: {
nav: [
{ text: 'Lab', link: '/lab/' },
{ text: 'Docs', link: '/docs/' },
{ text: 'Audit', link: '/audit/' },
{ text: 'KB', link: '/kb/' }
]
}
})1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
Environment Variables
| Variable | Description | Default |
|---|---|---|
DOCS_HUB_DIR | Output directory | ../docs-hub |
VITEPRESS_PORT | Dev server port | 5173 |
VITEPRESS_HOST | Dev server host | localhost |
Return Values
generate() Return Value
Returns None. Files are written directly to hub_dir.
Check for success:
python
import os
gen.generate()
index_path = hub_dir / "index.md"
if index_path.exists():
print("Success!")1
2
3
4
5
6
2
3
4
5
6
Error Handling
python
from docs_engine.hub.generator import HubGenerator
from pathlib import Path
try:
gen = HubGenerator(
hub_dir=Path("./phenodocs"),
projects={"test": "/nonexistent/path"}
)
gen.generate()
except FileNotFoundError as e:
print(f"Project path not found: {e}")
except PermissionError as e:
print(f"Permission denied: {e}")1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
TypeScript API
generateHubConfig()
typescript
import { defineConfig } from 'vitepress'
interface Project {
name: string
path: string
}
export function generateHubConfig(projects: Project[]) {
return defineConfig({
title: 'PhenoDocs',
themeConfig: {
nav: projects.map(p => ({
text: p.name,
link: `${p.path}/`
}))
}
})
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Webhooks
Hub Update Webhook
Trigger hub regeneration on doc changes:
yaml
# .github/workflows/hub-update.yml
on:
push:
paths:
- 'docs/**'
- '!docs/**/*.md' # exclude docs themselves
jobs:
update-hub:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate Hub
run: docs hub --hub-dir ./phenodocs
- name: Commit changes
run: |
git config --local user.email "bot@phenodocs.io"
git config --local user.name "PhenoDocs Bot"
git add .
git commit -m "Update hub" || exit 01
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Rate Limits
No rate limits for local generation. For CI/CD:
- Debounce: Wait 30s after last commit
- Cooldown: Max 1 generation per 5 minutes