112 lines
4.2 KiB
Markdown
112 lines
4.2 KiB
Markdown
|
---
|
||
|
|
title: Doc Sync
|
||
|
|
description: Documentation sync command for collecting docs from multi-repo workspaces into a central location.
|
||
|
|
---
|
||
|
|
|
||
|
|
# Doc Sync
|
||
|
|
|
||
|
|
The `core docs` commands scan a multi-repo workspace for documentation and sync it to a central location. This enables unified documentation builds across federated monorepos.
|
||
|
|
|
||
|
|
## Commands
|
||
|
|
|
||
|
|
### core docs list
|
||
|
|
|
||
|
|
Scan all repos in the workspace and display a table showing documentation coverage:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
core docs list # Uses auto-detected repos.yaml
|
||
|
|
core docs list --registry path/to/repos.yaml
|
||
|
|
```
|
||
|
|
|
||
|
|
Output shows which repos have:
|
||
|
|
- `README.md`
|
||
|
|
- `CLAUDE.md`
|
||
|
|
- `CHANGELOG.md`
|
||
|
|
- `docs/` directory (with file count)
|
||
|
|
|
||
|
|
### core docs sync
|
||
|
|
|
||
|
|
Copy `docs/` directories from all repos into a central output location:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
core docs sync # Sync to default target (php)
|
||
|
|
core docs sync --dry-run # Preview without writing
|
||
|
|
core docs sync --target gohelp # Sync to go-help format
|
||
|
|
core docs sync --target zensical # Sync to Zensical/Hugo format
|
||
|
|
core docs sync --output /path/to/dest # Custom output directory
|
||
|
|
core docs sync --registry repos.yaml # Explicit registry file
|
||
|
|
```
|
||
|
|
|
||
|
|
## Sync targets
|
||
|
|
|
||
|
|
The `--target` flag controls the output format and default destination:
|
||
|
|
|
||
|
|
### php (default)
|
||
|
|
|
||
|
|
Copies documentation to `core-php/docs/packages/{name}/`. Each repo's `docs/` directory is copied as-is, with directory names mapped:
|
||
|
|
|
||
|
|
- `core` maps to `packages/go/`
|
||
|
|
- `core-admin` maps to `packages/admin/`
|
||
|
|
- `core-api` maps to `packages/api/`
|
||
|
|
|
||
|
|
Skips `core-php` (the destination) and `core-template`.
|
||
|
|
|
||
|
|
### gohelp
|
||
|
|
|
||
|
|
Plain copy to a go-help content directory (`docs/content/` by default). No frontmatter injection. Directory names follow the same mapping as the php target.
|
||
|
|
|
||
|
|
### zensical
|
||
|
|
|
||
|
|
Copies to a Zensical/Hugo docs directory (`docs-site/docs/` by default) with automatic Hugo frontmatter injection. Repos are mapped to content sections:
|
||
|
|
|
||
|
|
| Repo pattern | Section | Folder |
|
||
|
|
|-------------|---------|--------|
|
||
|
|
| `cli` | `getting-started` | — |
|
||
|
|
| `core` | `cli` | — |
|
||
|
|
| `go-*` | `go` | repo name |
|
||
|
|
| `core-*` | `php` | name without prefix |
|
||
|
|
|
||
|
|
Frontmatter (title and weight) is added to markdown files that lack it. READMEs become `index.md` files. `KB/` directories are synced to a `kb/` section.
|
||
|
|
|
||
|
|
## How it works
|
||
|
|
|
||
|
|
1. **Load registry** — finds `repos.yaml` (auto-detected or explicit path) and loads the repo list. Respects `workspace.yaml` for custom `packages_dir`.
|
||
|
|
2. **Scan repos** — walks each repo looking for `README.md`, `CLAUDE.md`, `CHANGELOG.md`, `docs/*.md` (recursive), and `KB/*.md` (recursive). The `docs/plans/` subdirectory is skipped.
|
||
|
|
3. **Display plan** — shows which repos have documentation and where files will be written.
|
||
|
|
4. **Confirm** — prompts for confirmation (skipped in `--dry-run` mode).
|
||
|
|
5. **Copy** — clears existing output directories and copies files. For the zensical target, injects Hugo frontmatter where missing.
|
||
|
|
|
||
|
|
## Flags
|
||
|
|
|
||
|
|
| Flag | Default | Description |
|
||
|
|
|------|---------|-------------|
|
||
|
|
| `--registry` | auto-detect | Path to `repos.yaml` |
|
||
|
|
| `--dry-run` | `false` | Preview sync plan without writing files |
|
||
|
|
| `--output` | target-dependent | Output directory (overrides target default) |
|
||
|
|
| `--target` | `php` | Output format: `php`, `gohelp`, or `zensical` |
|
||
|
|
|
||
|
|
## Registry discovery
|
||
|
|
|
||
|
|
The registry (list of repos) is found by:
|
||
|
|
|
||
|
|
1. Explicit `--registry` path if provided.
|
||
|
|
2. Auto-detection: `repos.yaml` in the current directory or parent directories.
|
||
|
|
3. Fallback: scan the current directory for git repositories.
|
||
|
|
|
||
|
|
If a `workspace.yaml` file exists alongside the registry, its `packages_dir` setting overrides the default repo path resolution.
|
||
|
|
|
||
|
|
## RepoDocInfo
|
||
|
|
|
||
|
|
Each scanned repo produces a `RepoDocInfo` struct:
|
||
|
|
|
||
|
|
| Field | Type | Description |
|
||
|
|
|-------|------|-------------|
|
||
|
|
| `Name` | `string` | Repository name |
|
||
|
|
| `Path` | `string` | Absolute filesystem path |
|
||
|
|
| `HasDocs` | `bool` | Whether any documentation was found |
|
||
|
|
| `Readme` | `string` | Path to `README.md` (empty if missing) |
|
||
|
|
| `ClaudeMd` | `string` | Path to `CLAUDE.md` (empty if missing) |
|
||
|
|
| `Changelog` | `string` | Path to `CHANGELOG.md` (empty if missing) |
|
||
|
|
| `DocsFiles` | `[]string` | Relative paths of files in `docs/` |
|
||
|
|
| `KBFiles` | `[]string` | Relative paths of files in `KB/` |
|