Skip to content

Commit 94a3736

Browse files
lgecsekeraronmuscariello
authored
feat(docs): migrate slim docs, add dev(main) and latest(vX.Y.Z) to docs deployment (agntcy#1720)
## Summary - Migrates SLIM documentation content, and CI from docs.agntcy.org - Adds SLIM frontpage to the documentation (to be re-designed in an another PR) - Adds SLIM community page - Adds links to the SLIM spec and Blogs - Adds versioned docs deployment with no client-side redirects: - Push to `main` publishes the `dev` version → served at `/dev/` - Release publishes `vX.Y.Z` aliased as `latest` (default) → served at `/latest/` <img width="1005" height="850" alt="image" src="https://github.com/user-attachments/assets/4186d3ff-f1d3-475f-90ef-1a1a8c7504ed" /> <img width="1005" height="833" alt="image" src="https://github.com/user-attachments/assets/3176f76c-3c20-4627-af12-243a4a571f72" /> <img width="1030" height="854" alt="image" src="https://github.com/user-attachments/assets/0389ddd8-17e7-4db1-915b-e3d17780c799" /> <img width="1044" height="851" alt="image" src="https://github.com/user-attachments/assets/b27c7188-82fb-431d-8335-1339276eedb0" /> <img width="430" height="745" alt="image" src="https://github.com/user-attachments/assets/0799b3a6-0a86-4d85-a937-d403ada6614f" /> <img width="517" height="729" alt="image" src="https://github.com/user-attachments/assets/80ebc5cc-f93e-400f-beac-c25e9de5b3cc" /> <img width="518" height="734" alt="image" src="https://github.com/user-attachments/assets/dd663c89-6ebc-41fc-a3e7-81f8cca2adec" /> --------- Signed-off-by: Laszlo Gecse <lgecse@cisco.com> Signed-off-by: Aron Kerekes <arkereke@cisco.com> Signed-off-by: Luca Muscariello <muscariello@ieee.org> Co-authored-by: Aron Kerekes <arkereke@cisco.com> Co-authored-by: Luca Muscariello <muscariello@ieee.org>
1 parent c8e9425 commit 94a3736

48 files changed

Lines changed: 8202 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs-ci.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Copyright AGNTCY Contributors (https://github.com/agntcy)
2+
# SPDX-License-Identifier: Apache-2.0
3+
#
4+
# Docs PR checks: build + lint via the reusable docs pipeline (mode: ci).
5+
6+
name: Documentation CI
7+
8+
on:
9+
pull_request:
10+
paths:
11+
- 'docs/**'
12+
- '.github/workflows/docs-ci.yaml'
13+
- '.github/workflows/reusable-docs.yml'
14+
15+
permissions:
16+
contents: read
17+
18+
jobs:
19+
ci:
20+
uses: ./.github/workflows/reusable-docs.yml
21+
with:
22+
mode: ci

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

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Copyright AGNTCY Contributors (https://github.com/agntcy)
2+
# SPDX-License-Identifier: Apache-2.0
3+
#
4+
# Docs deploys via the reusable docs pipeline:
5+
# - push to main -> mode deploy-dev (`dev` version; never `latest`)
6+
# - release tag vX.Y.Z -> mode deploy-release (`X.Y.Z` + `latest`, default)
7+
# - workflow_dispatch -> mode deploy-release, version from input
8+
#
9+
# gh-pages is the version ledger (mike --push). Event parsing lives here (needs
10+
# the GitHub event context); the mike/task mechanics live in docs/Taskfile.yml.
11+
12+
name: Documentation Deploy
13+
14+
on:
15+
push:
16+
branches: [main]
17+
paths:
18+
- 'docs/**'
19+
- '.github/workflows/docs-deploy.yml'
20+
- '.github/workflows/reusable-docs.yml'
21+
tags:
22+
- 'v*.*.*'
23+
release:
24+
types: [published]
25+
workflow_dispatch:
26+
inputs:
27+
version:
28+
description: 'Docs version label for mike (e.g. 1.2.0; no leading v required)'
29+
required: true
30+
type: string
31+
32+
permissions:
33+
contents: read
34+
35+
# Serialize gh-pages updates so concurrent mike pushes do not race.
36+
concurrency:
37+
group: docs-deploy-pages
38+
cancel-in-progress: false
39+
40+
jobs:
41+
resolve:
42+
name: Resolve deploy mode + version
43+
runs-on: ubuntu-latest
44+
outputs:
45+
mode: ${{ steps.r.outputs.mode }}
46+
version: ${{ steps.r.outputs.version }}
47+
steps:
48+
- name: Resolve mode and version
49+
id: r
50+
shell: bash
51+
env:
52+
EVENT_NAME: ${{ github.event_name }}
53+
REF: ${{ github.ref }}
54+
REF_TYPE: ${{ github.ref_type }}
55+
REF_NAME: ${{ github.ref_name }}
56+
RELEASE_TAG: ${{ github.event.release.tag_name }}
57+
INPUT_VERSION: ${{ github.event.inputs.version }}
58+
run: |
59+
set -euo pipefail
60+
MODE=""
61+
VERSION=""
62+
if [ "${EVENT_NAME}" = "push" ] && [ "${REF}" = "refs/heads/main" ]; then
63+
MODE="deploy-dev"
64+
elif [ "${EVENT_NAME}" = "workflow_dispatch" ]; then
65+
MODE="deploy-release"
66+
VERSION="${INPUT_VERSION}"
67+
elif [ "${EVENT_NAME}" = "release" ] && [ -n "${RELEASE_TAG:-}" ]; then
68+
MODE="deploy-release"
69+
VERSION="${RELEASE_TAG}"
70+
elif [ "${REF_TYPE}" = "tag" ]; then
71+
MODE="deploy-release"
72+
VERSION="${REF_NAME}"
73+
else
74+
echo "::error::Could not resolve deploy mode from event ${EVENT_NAME} (${REF})"
75+
exit 1
76+
fi
77+
echo "mode=${MODE}" >> "${GITHUB_OUTPUT}"
78+
echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
79+
echo "Resolved mode=${MODE} version=${VERSION:-<none>}"
80+
81+
deploy:
82+
needs: resolve
83+
permissions:
84+
contents: write
85+
uses: ./.github/workflows/reusable-docs.yml
86+
with:
87+
mode: ${{ needs.resolve.outputs.mode }}
88+
version: ${{ needs.resolve.outputs.version }}

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

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Copyright AGNTCY Contributors (https://github.com/agntcy)
2+
# SPDX-License-Identifier: Apache-2.0
3+
#
4+
# Reusable docs pipeline for https://agntcy.github.io/slim/. Provisions tools
5+
# (uv, task, lychee) and calls task entries from docs/Taskfile.yml. All build,
6+
# lint, and deploy logic lives in the Taskfile; this only wires it to CI.
7+
#
8+
# Behavior by `mode`:
9+
# ci -> task docs:ci (build + lint)
10+
# deploy-dev -> build + lint, then docs:deploy:dev (`dev` version) + docs:deploy:root-files
11+
# deploy-release -> docs:deploy:release VERSION=<v> + docs:deploy:root-files
12+
13+
name: Reusable Docs
14+
15+
on:
16+
workflow_call:
17+
inputs:
18+
mode:
19+
description: "ci | deploy-dev | deploy-release"
20+
required: true
21+
type: string
22+
version:
23+
description: "Raw version label for deploy-release (leading v stripped by the task)"
24+
required: false
25+
type: string
26+
default: ""
27+
28+
jobs:
29+
docs:
30+
name: Docs (${{ inputs.mode }})
31+
runs-on: ubuntu-latest
32+
# GITHUB_TOKEN permissions are controlled by the caller:
33+
# docs-ci.yaml -> contents: read (lint/build only)
34+
# docs-deploy.yml deploy job -> contents: write (mike --push, root files)
35+
steps:
36+
- name: Checkout code
37+
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
38+
with:
39+
# mike needs full history and the gh-pages branch to deploy versions.
40+
fetch-depth: 0
41+
persist-credentials: false
42+
43+
- name: Setup uv
44+
uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
45+
46+
- name: Setup task
47+
uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
48+
49+
- name: Install lychee (link checker)
50+
if: inputs.mode == 'ci' || inputs.mode == 'deploy-dev'
51+
shell: bash
52+
run: |
53+
curl -sSfL https://github.com/lycheeverse/lychee/releases/download/lychee-v0.18.1/lychee-x86_64-unknown-linux-gnu.tar.gz \
54+
| tar xzv
55+
sudo mv lychee /usr/local/bin/lychee
56+
lychee --version
57+
58+
- name: CI checks (build + lint)
59+
if: inputs.mode == 'ci' || inputs.mode == 'deploy-dev'
60+
shell: bash
61+
run: task docs:ci
62+
63+
- name: Deploy dev
64+
if: inputs.mode == 'deploy-dev'
65+
shell: bash
66+
run: task docs:deploy:dev
67+
68+
- name: Deploy release version + latest
69+
if: inputs.mode == 'deploy-release'
70+
shell: bash
71+
env:
72+
VERSION_INPUT: ${{ inputs.version }}
73+
run: task docs:deploy:release VERSION="${VERSION_INPUT}"
74+
75+
- name: Deploy root-level files (404/robots/llms)
76+
if: inputs.mode == 'deploy-dev' || inputs.mode == 'deploy-release'
77+
shell: bash
78+
env:
79+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
80+
REPO_SLUG: ${{ github.repository }}
81+
run: task docs:deploy:root-files

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,3 +146,9 @@ libslim_bindings.a
146146

147147
# Backup files
148148
*.bak
149+
150+
# Docs build output (task docs:build / mkdocs)
151+
.build/
152+
docs/mkdocs/site/
153+
docs/mkdocs/.venv/
154+
docs/.task/

‎Taskfile.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ includes:
88
taskfile: data-plane/Taskfile.yaml
99
flatten: true
1010
dir: ./data-plane
11+
docs:
12+
taskfile: docs/Taskfile.yml
13+
excludes: [default]
1114

1215
silent: true
1316

‎docs/README.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# SLIM documentation
2+
3+
MkDocs site for [agntcy/slim](https://github.com/agntcy/slim), published at [https://agntcy.github.io/slim/](https://agntcy.github.io/slim/) with a **version selector** (latest release by default, older releases in the dropdown).
4+
5+
## Layout
6+
7+
| Path | Purpose |
8+
|------|---------|
9+
| `content/` | Published Markdown |
10+
| `mkdocs/` | MkDocs config, uv project, theme overrides |
11+
| `Taskfile.yml` | Build, serve, lint, and local mike preview tasks |
12+
13+
## Prerequisites
14+
15+
- [Task](https://taskfile.dev/)
16+
- [uv](https://docs.astral.sh/uv/)
17+
- [lychee](https://github.com/lycheeverse/lychee) (required for `task docs:ci` / `task docs:test`; installed automatically in CI)
18+
19+
Lint checks run on published nav content (`content/index.md` and `content/slim/`), not orphan pages under `content/`.
20+
21+
## Commands (from repo root)
22+
23+
```bash
24+
task docs:run # live preview while editing (no version dropdown)
25+
task docs:build # static site → .build/site
26+
task docs:ci # build + lint (same as PR CI)
27+
task docs:test # lint only
28+
task docs:mike:deploy-local # versioned preview on local gh-pages (no push)
29+
task docs:mike:serve # serve local gh-pages (after deploy-local)
30+
```
31+
32+
From `docs/`:
33+
34+
```bash
35+
task run
36+
task -t Taskfile.yml ci
37+
```
38+
39+
## CI and deploy
40+
41+
All build, lint, and deploy logic lives in [`Taskfile.yml`](Taskfile.yml). The GitHub Actions workflows are thin: they provision tools (`uv`, `task`, `lychee`) and call task entries. Dependencies come from `mkdocs/pyproject.toml` / `mkdocs/uv.lock` via `task` → `uv sync`.
42+
43+
- [`.github/workflows/reusable-docs.yml`](../.github/workflows/reusable-docs.yml) — reusable pipeline (`workflow_call`) with a `mode` input (`ci` / `deploy-dev` / `deploy-release`); holds the shared setup + task calls.
44+
- [`.github/workflows/docs-ci.yaml`](../.github/workflows/docs-ci.yaml) — on pull requests, calls the reusable pipeline with `mode: ci`.
45+
- [`.github/workflows/docs-deploy.yml`](../.github/workflows/docs-deploy.yml) — on push to `main`, `v*.*.*` tags, releases, and manual dispatch; resolves the mode/version from the event and calls the reusable pipeline.
46+
47+
| Trigger | Mode | Task(s) invoked | Effect |
48+
| --- | --- | --- | --- |
49+
| Pull request (touching `docs/**` or the workflows) | `ci` | `task docs:ci` | Build + lint (codespell, pymarkdown, lychee). No deploy. |
50+
| Push to `main` | `deploy-dev` | `task docs:ci` + `docs:deploy:dev` + `docs:deploy:root-files` | Build + lint, then `mike deploy --push dev` (the `dev` version). **Never touches `latest`.** |
51+
| Release published / `v*.*.*` tag / manual dispatch | `deploy-release` | `task docs:deploy:release VERSION=<v>` + `docs:deploy:root-files` | `mike deploy --push --update-aliases <version> latest` then `mike set-default latest`, so https://agntcy.github.io/slim/ opens the latest release. |
52+
53+
Deploys use [mike](https://github.com/jimporter/mike) to push each version into a subdirectory of the `gh-pages` branch (the version ledger). `dev` is published as its own version (push to `main`) and `latest` is an alias of the newest release. With `alias_type: copy` plus `canonical_version: latest`, the `latest` alias is a full standalone copy of the release version, so both `/dev/` and `/latest/` serve content in place (HTTP 200, no redirect). Older versions stay in the dropdown; prune with `mike delete` when retiring doc releases. The `docs:deploy:*` tasks push to the remote, so they refuse to run outside CI unless `ALLOW_DOCS_PUSH=1` is set; root-file publishing reads its token from the `GH_TOKEN` environment variable (`REPO_SLUG` selects the repo).
54+
55+
GitHub Pages serves directly from the `gh-pages` branch (**Settings → Pages → Build and deployment → Deploy from a branch → `gh-pages`**).
56+
57+
### Local version-selector preview
58+
59+
```bash
60+
# Optional: fetch existing versions from origin
61+
git fetch origin gh-pages
62+
63+
task docs:mike:deploy-local # deploys the current docs to local gh-pages as `dev` (no push)
64+
task docs:mike:serve # http://127.0.0.1:8000/ with the version dropdown
65+
```

0 commit comments

Comments
 (0)