119 lines
2.9 KiB
Markdown
119 lines
2.9 KiB
Markdown
# Docs Services Automation Runbook
|
|
|
|
Date: 2026-02-16
|
|
Scope: GitHub, Gitea, Jupyter, Pieces documentation integration workflow.
|
|
|
|
## Goal
|
|
|
|
Keep docs state synchronized with service reality and publish curated docs updates safely.
|
|
|
|
## 1) Refresh service status
|
|
|
|
```bash
|
|
cd /Users/apple/github-projects/microdao-daarion
|
|
bash scripts/docs/session_bootstrap.sh
|
|
```
|
|
|
|
Primary output:
|
|
- `docs/consolidation/INTEGRATIONS_STATUS_LATEST.md`
|
|
|
|
## 2) Run service adapters (Jupyter + Pieces)
|
|
|
|
```bash
|
|
cd /Users/apple/github-projects/microdao-daarion
|
|
bash scripts/docs/services_sync.sh --dry-run
|
|
```
|
|
|
|
Apply mode:
|
|
|
|
```bash
|
|
cd /Users/apple/github-projects/microdao-daarion
|
|
bash scripts/docs/services_sync.sh --apply
|
|
```
|
|
|
|
Optional local Pieces API probe:
|
|
|
|
```bash
|
|
cd /Users/apple/github-projects/microdao-daarion
|
|
bash scripts/docs/services_sync.sh --apply --probe-ports 39300,39301
|
|
```
|
|
|
|
Outputs:
|
|
- `docs/consolidation/jupyter/JUPYTER_SYNC_LATEST.md`
|
|
- `docs/consolidation/jupyter/notebooks_index_latest.csv`
|
|
- `docs/consolidation/pieces/PIECES_SYNC_LATEST.md`
|
|
- `docs/consolidation/pieces/pieces_index_latest.csv`
|
|
- `docs/backups/LATEST.txt` (latest backup archive reference)
|
|
|
|
## 3) Review pending docs updates
|
|
|
|
```bash
|
|
cd /Users/apple/github-projects/microdao-daarion
|
|
git status --short
|
|
bash scripts/docs/docs_sync.sh --dry-run
|
|
```
|
|
|
|
## 4) Apply sync to remotes
|
|
|
|
```bash
|
|
cd /Users/apple/github-projects/microdao-daarion
|
|
bash scripts/docs/docs_sync.sh --apply --targets github,gitea
|
|
```
|
|
|
|
## 5) Local scheduled run (no auto-push)
|
|
|
|
Install/update daily cron job (local timezone):
|
|
|
|
```bash
|
|
cd /Users/apple/github-projects/microdao-daarion
|
|
bash scripts/docs/install_local_cron.sh --schedule "17 9 * * *"
|
|
```
|
|
|
|
Dry-run preview:
|
|
|
|
```bash
|
|
cd /Users/apple/github-projects/microdao-daarion
|
|
bash scripts/docs/install_local_cron.sh --dry-run
|
|
```
|
|
|
|
Uninstall:
|
|
|
|
```bash
|
|
cd /Users/apple/github-projects/microdao-daarion
|
|
bash scripts/docs/install_local_cron.sh --uninstall
|
|
```
|
|
|
|
Runner command:
|
|
- `scripts/docs/run_docs_maintenance.sh`
|
|
- executes `services_sync --apply` and `docs_lint`
|
|
- does not perform any `git push`
|
|
|
|
## Safety gates
|
|
|
|
- `docs_sync.sh` is dry-run by default.
|
|
- `--apply` refuses to proceed if staged non-doc files are present.
|
|
- Only curated doc paths are auto-staged by the script.
|
|
- `services_sync.sh --apply` creates docs backup before writing integration artifacts.
|
|
|
|
## Standardization and lint
|
|
|
|
Local lint:
|
|
|
|
```bash
|
|
cd /Users/apple/github-projects/microdao-daarion
|
|
bash scripts/docs/docs_lint.sh
|
|
```
|
|
|
|
CI lint:
|
|
- `.github/workflows/docs-lint.yml`
|
|
- config: `.markdownlint.yml`, `.markdownlintignore`
|
|
|
|
Style and template:
|
|
- `docs/standards/DOCS_STYLE_GUIDE.md`
|
|
- `docs/standards/DOC_TEMPLATE.md`
|
|
|
|
## Jupyter and Pieces notes
|
|
|
|
- `jupyter_sync.sh` probes active Jupyter servers via `/api/status` when servers are discovered.
|
|
- `pieces_sync.sh` captures local Pieces runtime markers and supports optional local API probes (`--probe-ports`).
|