Skip to content

Commit 18bc477

Browse files
cursoragentjasondamour
cursoragent
and
jasondamour
committed
feat: Add GitHub Actions for docs and changelog publishing
Co-authored-by: jason <jason@lumos.com>
1 parent da7fa52 commit 18bc477

File tree

8 files changed

+583
-4
lines changed

8 files changed

+583
-4
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
name: Publish Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/sphinx/**'
9+
- 'docs/scripts/**'
10+
- 'docs/Makefile'
11+
- 'src/lumos_cli/**'
12+
workflow_dispatch:
13+
inputs:
14+
publish-mode:
15+
description: 'Publish mode for readme.io'
16+
required: true
17+
type: choice
18+
options:
19+
- draft
20+
- public
21+
default: draft
22+
23+
env:
24+
# readme.io project configuration
25+
READMEIO_CATEGORY_SLUG: reference
26+
27+
jobs:
28+
build-docs:
29+
name: Build Documentation
30+
runs-on: ubuntu-latest
31+
outputs:
32+
docs-changed: ${{ steps.check-changes.outputs.changed }}
33+
steps:
34+
- name: Checkout code
35+
uses: actions/checkout@v4
36+
with:
37+
fetch-depth: 2
38+
39+
- name: Check for documentation changes
40+
id: check-changes
41+
run: |
42+
if git diff --name-only HEAD~1 HEAD | grep -qE '^docs/|^src/lumos_cli/'; then
43+
echo "changed=true" >> $GITHUB_OUTPUT
44+
else
45+
echo "changed=false" >> $GITHUB_OUTPUT
46+
fi
47+
48+
- name: Setup Python
49+
uses: actions/setup-python@v5
50+
with:
51+
python-version: '3.10.6'
52+
53+
- name: Setup UV
54+
uses: astral-sh/setup-uv@v4
55+
with:
56+
version: latest
57+
enable-cache: true
58+
59+
- name: Install dependencies
60+
run: uv sync --group docs
61+
62+
- name: Build documentation
63+
run: make -C docs docs
64+
65+
- name: Upload readme.io docs artifact
66+
uses: actions/upload-artifact@v4
67+
with:
68+
name: readme-io-docs
69+
path: docs/readme.io/
70+
retention-days: 7
71+
72+
- name: Upload HTML docs artifact
73+
uses: actions/upload-artifact@v4
74+
with:
75+
name: html-docs
76+
path: docs/sphinx/_build/html/
77+
retention-days: 7
78+
79+
publish-to-readme:
80+
name: Publish to readme.io
81+
needs: build-docs
82+
runs-on: ubuntu-latest
83+
# Only run on main branch pushes or manual dispatch
84+
if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main')
85+
steps:
86+
- name: Download readme.io docs
87+
uses: actions/download-artifact@v4
88+
with:
89+
name: readme-io-docs
90+
path: readme-io-docs/
91+
92+
- name: Setup Node.js
93+
uses: actions/setup-node@v4
94+
with:
95+
node-version: 'lts/*'
96+
97+
- name: Install rdme CLI
98+
run: npm install -g rdme
99+
100+
- name: Determine publish mode
101+
id: publish-mode
102+
run: |
103+
if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
104+
echo "mode=${{ inputs.publish-mode }}" >> $GITHUB_OUTPUT
105+
else
106+
# Default to draft for automated pushes
107+
echo "mode=draft" >> $GITHUB_OUTPUT
108+
fi
109+
110+
- name: Publish docs to readme.io (Draft)
111+
if: steps.publish-mode.outputs.mode == 'draft'
112+
env:
113+
RDME_API_KEY: ${{ secrets.README_API_KEY }}
114+
run: |
115+
echo "Publishing documentation as draft to readme.io..."
116+
rdme docs readme-io-docs/ \
117+
--key "$RDME_API_KEY" \
118+
--version "main" \
119+
--dryRun || true
120+
121+
echo ""
122+
echo "=================================================="
123+
echo "📝 DRAFT MODE: Documentation changes staged"
124+
echo "=================================================="
125+
echo ""
126+
echo "To review and publish:"
127+
echo "1. Go to https://dash.readme.com/project/lumos-developers"
128+
echo "2. Review the documentation changes in the 'main' version"
129+
echo "3. When ready, run this workflow manually with 'public' mode"
130+
echo ""
131+
132+
- name: Publish docs to readme.io (Public)
133+
if: steps.publish-mode.outputs.mode == 'public'
134+
env:
135+
RDME_API_KEY: ${{ secrets.README_API_KEY }}
136+
run: |
137+
echo "Publishing documentation to readme.io..."
138+
rdme docs readme-io-docs/ \
139+
--key "$RDME_API_KEY" \
140+
--version "main"
141+
142+
echo ""
143+
echo "=================================================="
144+
echo "✅ Documentation published to readme.io"
145+
echo "=================================================="
146+
echo ""
147+
echo "View at: https://developers.lumos.com/reference/lumos-cli"
148+
echo ""
149+
150+
notify-on-failure:
151+
name: Notify on Failure
152+
needs: [build-docs, publish-to-readme]
153+
runs-on: ubuntu-latest
154+
if: failure()
155+
steps:
156+
- name: Create failure summary
157+
run: |
158+
echo "## ❌ Documentation Publishing Failed" >> $GITHUB_STEP_SUMMARY
159+
echo "" >> $GITHUB_STEP_SUMMARY
160+
echo "The documentation workflow failed. Please check the logs for details." >> $GITHUB_STEP_SUMMARY
161+
echo "" >> $GITHUB_STEP_SUMMARY
162+
echo "**Workflow run:** ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" >> $GITHUB_STEP_SUMMARY

‎.github/workflows/release.yml‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,3 +137,149 @@ jobs:
137137
-H "Accept: application/vnd.github+json" \
138138
https://api.github.com/repos/teamlumos/homebrew-tap/dispatches \
139139
-d '{"event_type": "release", "client_payload": {"version": "${{ needs.prepare.outputs.new-release-version }}"}}'
140+
141+
publish-changelog:
142+
name: Publish Changelog to readme.io
143+
needs: [prepare, release]
144+
if: inputs.dry-run != 'true'
145+
runs-on: ubuntu-latest
146+
steps:
147+
- name: Checkout code
148+
uses: actions/checkout@v4
149+
with:
150+
ref: main
151+
fetch-depth: 0
152+
153+
- name: Setup Node.js
154+
uses: actions/setup-node@v4
155+
with:
156+
node-version: 'lts/*'
157+
158+
- name: Install rdme CLI
159+
run: npm install -g rdme
160+
161+
- name: Extract release notes
162+
id: release-notes
163+
run: |
164+
VERSION="v${{ needs.prepare.outputs.new-release-version }}"
165+
166+
# Extract the changelog section for this version
167+
# The changelog format is: # [X.Y.Z](url) (date) followed by content until the next # [
168+
CHANGELOG_CONTENT=$(awk -v ver="${VERSION#v}" '
169+
/^# \[/ {
170+
if (found) exit
171+
if ($0 ~ "\\[" ver "\\]") found=1
172+
}
173+
found
174+
' CHANGELOG.md)
175+
176+
# Write to file for the API call
177+
echo "$CHANGELOG_CONTENT" > release_notes.md
178+
179+
# Set output for use in subsequent steps
180+
echo "version=$VERSION" >> $GITHUB_OUTPUT
181+
182+
- name: Publish changelog to readme.io
183+
env:
184+
RDME_API_KEY: ${{ secrets.README_API_KEY }}
185+
run: |
186+
VERSION="${{ steps.release-notes.outputs.version }}"
187+
TITLE="Lumos CLI ${VERSION}"
188+
189+
# Create changelog entry JSON
190+
cat > changelog_entry.json << EOF
191+
{
192+
"title": "${TITLE}",
193+
"type": "added",
194+
"body": $(cat release_notes.md | jq -Rs .)
195+
}
196+
EOF
197+
198+
echo "Publishing changelog for ${VERSION} to readme.io..."
199+
200+
# Use rdme to create changelog entry
201+
# Note: rdme changelogs command creates entries at https://developers.lumos.com/changelog
202+
rdme changelogs changelog_entry.json --key "$RDME_API_KEY" || {
203+
echo "Warning: Failed to publish changelog via rdme, attempting direct API call..."
204+
205+
# Fallback to direct API call if rdme doesn't support the format
206+
curl -X POST "https://dash.readme.com/api/v1/changelogs" \
207+
-H "Authorization: Basic $(echo -n "${RDME_API_KEY}:" | base64)" \
208+
-H "Content-Type: application/json" \
209+
-d @changelog_entry.json
210+
}
211+
212+
echo ""
213+
echo "=================================================="
214+
echo "✅ Changelog published to readme.io"
215+
echo "=================================================="
216+
echo ""
217+
echo "View at: https://developers.lumos.com/changelog"
218+
echo ""
219+
220+
publish-docs:
221+
name: Publish Documentation to readme.io
222+
needs: [prepare, release]
223+
if: inputs.dry-run != 'true'
224+
runs-on: ubuntu-latest
225+
steps:
226+
- name: Checkout code
227+
uses: actions/checkout@v4
228+
with:
229+
ref: main
230+
fetch-depth: 0
231+
232+
- name: Setup Python
233+
uses: actions/setup-python@v5
234+
with:
235+
python-version: '3.10.6'
236+
237+
- name: Setup UV
238+
uses: astral-sh/setup-uv@v4
239+
with:
240+
version: latest
241+
enable-cache: true
242+
243+
- name: Setup Node.js
244+
uses: actions/setup-node@v4
245+
with:
246+
node-version: 'lts/*'
247+
248+
- name: Install rdme CLI
249+
run: npm install -g rdme
250+
251+
- name: Install Python dependencies
252+
run: uv sync --group docs
253+
254+
- name: Build documentation
255+
run: make -C docs docs
256+
257+
- name: Publish docs to readme.io (Draft for review)
258+
env:
259+
RDME_API_KEY: ${{ secrets.README_API_KEY }}
260+
run: |
261+
VERSION="${{ needs.prepare.outputs.new-release-version }}"
262+
263+
echo "Publishing documentation as draft for version ${VERSION}..."
264+
265+
# First publish as a new draft version for review
266+
rdme docs docs/readme.io/ \
267+
--key "$RDME_API_KEY" \
268+
--version "${VERSION}" \
269+
--create-version || rdme docs docs/readme.io/ \
270+
--key "$RDME_API_KEY" \
271+
--version "${VERSION}"
272+
273+
echo ""
274+
echo "=================================================="
275+
echo "📝 Documentation published as draft version ${VERSION}"
276+
echo "=================================================="
277+
echo ""
278+
echo "To review and make public:"
279+
echo "1. Go to https://dash.readme.com/project/lumos-developers"
280+
echo "2. Review the documentation in version '${VERSION}'"
281+
echo "3. When ready, promote this version to stable"
282+
echo ""
283+
echo "Documentation will be visible at:"
284+
echo "https://developers.lumos.com/reference/lumos-cli"
285+
echo ""

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,4 @@ node_modules/
1212

1313
# Documentation build output
1414
docs/sphinx/_build/
15+
docs/readme.io/

‎docs/Makefile‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,23 @@ SPHINXOPTS ?=
44
SPHINXBUILD ?= uv run sphinx-build
55
SPHINXDIR = sphinx
66
BUILDDIR = $(SPHINXDIR)/_build
7+
READMEIODIR = readme.io
78

8-
.PHONY: help clean html markdown docs
9+
.PHONY: help clean html markdown readme-io docs
910

1011
# Put it first so that "make" without argument is like "make help".
1112
help:
1213
@echo "Available targets:"
1314
@echo " html - Build HTML documentation"
1415
@echo " markdown - Build Markdown documentation"
15-
@echo " docs - Build both"
16+
@echo " readme-io - Generate readme.io docs with frontmatter"
17+
@echo " docs - Build all (markdown, html, and readme.io)"
1618
@echo " clean - Remove build artifacts"
1719

1820
# Clean build directory
1921
clean:
2022
rm -rf $(BUILDDIR)
23+
rm -rf $(READMEIODIR)
2124
rm -f *.md
2225

2326
# Build HTML documentation
@@ -32,5 +35,10 @@ markdown:
3235
@cp $(BUILDDIR)/markdown/*.md .
3336
@echo "Markdown files copied to docs/"
3437

35-
# Build both
36-
docs: markdown html
38+
# Generate readme.io documentation with YAML frontmatter
39+
readme-io: markdown
40+
@uv run python scripts/generate_readme_docs.py --source-dir . --output-dir $(READMEIODIR)
41+
@echo "readme.io docs generated in $(READMEIODIR)/"
42+
43+
# Build all documentation
44+
docs: markdown html readme-io

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ lumos request
3636
* [Installation](installation.md)
3737
* [macOS and Linux (via Homebrew)](installation.md#macos-and-linux-via-homebrew)
3838
* [Python Package (via pip or uv)](installation.md#python-package-via-pip-or-uv)
39+
* [Install from Source](installation.md#install-from-source)
3940
* [Binary Downloads](installation.md#binary-downloads)
4041
* [Initial Setup](installation.md#initial-setup)
4142
* [Troubleshooting](installation.md#troubleshooting)

0 commit comments

Comments
 (0)