Skip to content

Commit 928cf60

Browse files
localpiboxlocalpibox
committed
docs: MkDocs Material + mike versioned docs site (per stack tag)
The docs branch carries a documentation site where each stack tag gets an immutable, browsable version (current + past), aligned with code tags. - mkdocs.yml: Material theme, mike version switcher, curated nav - scripts/generate.py (stdlib): materializes the derived docs/ tree from the tracked content (README, doc/, support/docs/, repo-workflow skill) and stamps repo-map.md + versions.md from the 6 repos at HEAD or --tag (devstack is never tagged: its release commit is reverse-resolved via git log -S on VERSION) - .github/workflows/docs-publish.yml: push to docs -> living 'edge' version; dispatch with tag -> immutable <tag> version + alias (latest/dev), root redirect via mike set-default; concurrency-guarded - DOCS.md: local build + version-cutting runbook - tracked content stays in place (syncs with dev via merges); docs/ and site/ are derived (gitignored) Verified locally: build, edge bootstrap, tag cut 0.0.52-lpb-dev with alias + root redirect, and per-tag repo/versions stamping.
1 parent ddd2e07 commit 928cf60

5 files changed

Lines changed: 444 additions & 0 deletions

File tree

‎.github/workflows/docs-publish.yml‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Docs publishing for the LocalPibox stack (MkDocs Material + mike 2.x).
2+
#
3+
# Versions:
4+
# edge — living docs (docs branch HEAD), refreshed on every push to docs
5+
# <tag> — immutable per-tag snapshots, e.g. 0.0.53-lpb-dev / 0.0.53-lpb
6+
# latest — alias → most recent stable (main pipeline) tag
7+
# dev — alias → most recent dev pipeline tag
8+
#
9+
# Two flows:
10+
# 1. push to `docs` branch → rebuild the living `edge` version
11+
# 2. workflow_dispatch with `tag` → cut an immutable version for a stack tag
12+
# and point the alias (default: latest) at it
13+
#
14+
# Output: `gh-pages` branch (mike's branch); GitHub Pages serves it from the
15+
# repo root: https://lpb-stack.github.io/devstack/<version>/
16+
#
17+
# Run the tag flow AFTER the code release is done (tags exist on all 5 repos).
18+
# Keep the `docs` branch merged with `dev` before cutting a version so the
19+
# hand-written content matches the tag.
20+
21+
name: docs
22+
23+
on:
24+
push:
25+
branches: [docs]
26+
workflow_dispatch:
27+
inputs:
28+
tag:
29+
description: "Stack tag to cut a docs version for (e.g. 0.0.53-lpb-dev)"
30+
required: false
31+
alias:
32+
description: "Alias for the new version (latest = stable, dev = dev pipeline)"
33+
required: false
34+
default: "latest"
35+
36+
# dev + main pipelines can both cut versions — serialize gh-pages deploys
37+
concurrency:
38+
group: docs-deploy
39+
cancel-in-progress: false
40+
41+
jobs:
42+
publish:
43+
runs-on: ubuntu-latest
44+
env:
45+
TAG: ${{ inputs.tag }}
46+
ALIAS: ${{ inputs.alias || 'latest' }}
47+
AGENT_DIR: ${{ github.workspace }}/ws/config
48+
LPB_AGENT_GIT: ${{ github.workspace }}/ws/git
49+
LPB_WORKSPACE_ROOT: ${{ github.workspace }}/ws
50+
steps:
51+
- name: Checkout docs branch
52+
uses: actions/checkout@v4
53+
with:
54+
ref: docs
55+
fetch-depth: 0
56+
57+
- name: Fetch stack repos (default branch, or $TAG when cutting)
58+
run: |
59+
set -e
60+
mkdir -p ws/git
61+
git clone --quiet https://github.com/lpb-stack/config.git ws/config
62+
for r in lpb-memory pi-subagents lemonade-pi-plugin; do
63+
git clone --quiet "https://github.com/lpb-stack/$r.git" "ws/git/$r"
64+
done
65+
git clone --quiet https://github.com/lpb-stack/pi.git ws/pi
66+
if [ -n "$TAG" ]; then
67+
for d in ws/config ws/git/lpb-memory ws/git/pi-subagents \
68+
ws/git/lemonade-pi-plugin ws/pi; do
69+
git -C "$d" fetch --quiet --depth 1 origin tag "$TAG"
70+
git -C "$d" checkout -q "$TAG"
71+
done
72+
fi
73+
74+
- name: Install docs tooling
75+
run: python3 -m pip install --quiet mkdocs-material mike
76+
77+
- name: Prepare docs tree + version stamp
78+
run: python3 scripts/generate.py ${TAG:+--tag "$TAG"}
79+
80+
- name: Configure git identity for mike
81+
run: |
82+
git config user.name "lpb-docs"
83+
git config user.email "ci@lpb-stack.dev"
84+
85+
- name: Publish living edge docs
86+
if: ${{ inputs.tag == '' }}
87+
run: |
88+
mike deploy edge --push
89+
# bootstrap: until the first tagged version exists, root → edge
90+
if [ -z "$(mike list | grep -v '^edge')" ]; then
91+
mike set-default edge --push
92+
fi
93+
94+
- name: Publish tagged version
95+
if: ${{ inputs.tag != '' }}
96+
run: |
97+
mike deploy "$TAG" "$ALIAS" --push --update-aliases
98+
if [ "$ALIAS" = "latest" ]; then
99+
mike set-default latest --push
100+
elif ! mike list | grep -q '\[latest\]'; then
101+
# dev-pipeline tag while no stable release exists yet
102+
mike set-default dev --push
103+
fi
104+
echo "Docs version: https://lpb-stack.github.io/devstack/$TAG/"

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,7 @@ __pycache__/
77
*.pyo
88
.env
99
node_modules/
10+
11+
# ── Docs site (docs branch: derived by scripts/generate.py) ───────────────
12+
/docs/
13+
/site/

‎DOCS.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Docs branch
2+
3+
This branch carries the documentation site for the LocalPibox stack
4+
(MkDocs Material + [mike](https://github.com/jimporter/mike)).
5+
6+
- **Content lives in place** — `README.md`, `doc/`, `support/docs/`,
7+
`.pi/skills/...` are the same files as on `dev`. Keep this branch merged
8+
with `dev` so hand-written docs never drift.
9+
- **`docs/` is derived** (gitignored) — `scripts/generate.py` copies the
10+
tracked content and stamps version pages (repo map, versions) from the
11+
6 stack repos. Run it before every build; CI does this automatically.
12+
- **Versions** are cut by `.github/workflows/docs-publish.yml`:
13+
- push to `docs` → living `edge` version (always newest content)
14+
- dispatch with `tag: 0.0.X-lpb[-dev]` → immutable per-tag version + alias
15+
(`latest` = stable, `dev` = dev pipeline)
16+
- root of the site redirects to `latest` (or `edge` until the first tag)
17+
- served from the `gh-pages` branch (mike's branch) by GitHub Pages
18+
19+
## Local build
20+
21+
```bash
22+
python3 -m pip install --user mkdocs-material mike
23+
python3 scripts/generate.py # or: --tag 0.0.53-lpb-dev
24+
mike serve # live preview at http://localhost:8000
25+
```
26+
27+
## Cutting a version (after a code release)
28+
29+
1. Merge `dev` into `docs` (content up to date), push.
30+
2. GitHub → Actions → **docs** → Run workflow → `tag: 0.0.X-lpb[-dev]`,
31+
`alias: latest` (stable) or `dev` (dev pipeline).
32+
3. Result: `https://lpb-stack.github.io/devstack/0.0.X-lpb[-dev]/`

‎mkdocs.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# LocalPibox stack docs — MkDocs Material + mike (per-tag versioning).
2+
#
3+
# Tracked content lives in place (README.md, doc/, support/docs/, ...) exactly
4+
# as on `dev`, so this branch stays in sync via merges. `scripts/generate.py`
5+
# materializes the derived `docs/` tree (copies + version stamping) before
6+
# every build — docs/ is gitignored, like the image is built from the source.
7+
#
8+
# Versions are cut with mike (see .github/workflows/docs-publish.yml):
9+
# tag 0.0.X-lpb-dev / 0.0.X-lpb → /devstack/<tag>/ (+ latest/dev aliases)
10+
11+
site_name: LocalPibox Stack
12+
site_description: Documentation for the LocalPibox development stack — versioned per stack tag
13+
site_url: https://lpb-stack.github.io/devstack/
14+
15+
docs_dir: docs
16+
site_dir: site
17+
18+
theme:
19+
name: material
20+
palette:
21+
- scheme: default
22+
primary: teal
23+
accent: teal
24+
toggle:
25+
icon: material/brightness-4
26+
name: Switch to dark mode
27+
- scheme: slate
28+
primary: teal
29+
accent: teal
30+
toggle:
31+
icon: material/brightness-7
32+
name: Switch to light mode
33+
features:
34+
- navigation.sections
35+
- navigation.top
36+
- content.code.copy
37+
- search.suggest
38+
- search.highlight
39+
40+
# Version switcher (mike)
41+
extra:
42+
version:
43+
provider: mike
44+
default: latest
45+
46+
markdown_extensions:
47+
- toc:
48+
permalink: true
49+
- tables
50+
- admonition
51+
- attr_list
52+
- md_in_html
53+
54+
nav:
55+
- Home: index.md
56+
- Repo map: repo-map.md
57+
- Stack versions: versions.md
58+
- Operations:
59+
- Subagent spawning: operations/subagent-spawning-pattern.md
60+
- Reference:
61+
- Fork improvements: reference/fork-improvements.md
62+
- lpb-memory analysis: reference/lpb-memory-analysis.md
63+
- Repo workflow skill: reference/repo-workflow-skill.md
64+
- Contributing: contributing.md

0 commit comments

Comments
 (0)