Skip to content

Commit 39806e9

Browse files
brunoborgesbrunoborges
committed
feat: add versioned documentation template and update site deployment workflow
1 parent 601db0d commit 39806e9

3 files changed

Lines changed: 352 additions & 18 deletions

File tree

‎.github/templates/versions.html‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<title>Documentation Versions - Copilot SDK for Java</title>
5+
<style>
6+
body {
7+
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
8+
max-width: 800px;
9+
margin: 50px auto;
10+
padding: 20px;
11+
background: #f6f8fa;
12+
}
13+
.container {
14+
background: white;
15+
padding: 40px;
16+
border-radius: 8px;
17+
box-shadow: 0 1px 3px rgba(0,0,0,0.1);
18+
}
19+
h1 {
20+
color: #24292e;
21+
margin-bottom: 10px;
22+
}
23+
.subtitle {
24+
color: #586069;
25+
margin-bottom: 30px;
26+
}
27+
.version-list {
28+
list-style: none;
29+
padding: 0;
30+
}
31+
.version-list li {
32+
margin: 15px 0;
33+
padding: 15px;
34+
background: #f6f8fa;
35+
border-radius: 6px;
36+
display: flex;
37+
align-items: center;
38+
justify-content: space-between;
39+
}
40+
.version-list li:hover {
41+
background: #ebeef1;
42+
}
43+
.version-list a {
44+
color: #0366d6;
45+
text-decoration: none;
46+
font-size: 18px;
47+
font-weight: 500;
48+
}
49+
.version-list a:hover {
50+
text-decoration: underline;
51+
}
52+
.badge {
53+
display: inline-block;
54+
padding: 4px 10px;
55+
border-radius: 20px;
56+
font-size: 12px;
57+
font-weight: 600;
58+
}
59+
.latest {
60+
background: #28a745;
61+
color: white;
62+
}
63+
.snapshot {
64+
background: #ffc107;
65+
color: #333;
66+
}
67+
.archived {
68+
background: #6c757d;
69+
color: white;
70+
}
71+
.warning {
72+
background: #fff3cd;
73+
border: 1px solid #ffc107;
74+
padding: 15px;
75+
border-radius: 5px;
76+
margin: 20px 0;
77+
color: #856404;
78+
}
79+
.info {
80+
background: #e7f3ff;
81+
border: 1px solid #0366d6;
82+
padding: 15px;
83+
border-radius: 5px;
84+
margin: 20px 0;
85+
color: #0366d6;
86+
}
87+
.footer {
88+
margin-top: 40px;
89+
padding-top: 20px;
90+
border-top: 1px solid #eaecef;
91+
color: #586069;
92+
font-size: 14px;
93+
text-align: center;
94+
}
95+
.footer a {
96+
color: #0366d6;
97+
}
98+
</style>
99+
</head>
100+
<body>
101+
<div class="container">
102+
<h1>📚 Copilot SDK for Java</h1>
103+
<p class="subtitle">Documentation Versions</p>
104+
105+
<div class="warning">
106+
⚠️ <strong>Disclaimer:</strong> This is an <strong>unofficial, community-driven SDK</strong> and is <strong>not supported or endorsed by GitHub</strong>. Use at your own risk.
107+
</div>
108+
109+
<div class="info">
110+
💡 <strong>Tip:</strong> We recommend using the <strong>Latest Release</strong> documentation unless you need features from an unreleased version.
111+
</div>
112+
113+
<h2>Available Versions</h2>
114+
<ul class="version-list">
115+
<!-- VERSION_LIST_PLACEHOLDER -->
116+
</ul>
117+
118+
<div class="footer">
119+
<p>
120+
<a href="https://github.com/copilot-community-sdk/copilot-sdk-java">GitHub Repository</a> ·
121+
<a href="https://central.sonatype.com/artifact/io.github.copilot-community-sdk/copilot-sdk">Maven Central</a>
122+
</p>
123+
</div>
124+
</div>
125+
</body>
126+
</html>

‎.github/workflows/site.yml‎

Lines changed: 122 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,164 @@
1-
# Simple workflow for deploying static content to GitHub Pages
1+
# Workflow for deploying versioned documentation to GitHub Pages
22
name: Deploy Maven Site to Pages
33

44
on:
5-
# Runs on pushes targeting the default branch
5+
# Runs on pushes targeting the default branch (publishes to /snapshot/)
66
push:
77
branches: ["main"]
8+
paths:
9+
- 'src/site/**'
10+
- 'src/main/java/**'
11+
- 'pom.xml'
12+
- '.github/workflows/site.yml'
813

9-
# Allows you to run this workflow manually from the Actions tab
14+
# Runs on release publish (publishes to / and /vX.Y.Z/)
15+
release:
16+
types: [published]
17+
18+
# Allows manual trigger
1019
workflow_dispatch:
20+
inputs:
21+
publish_as_latest:
22+
description: 'Also publish as latest (root path)?'
23+
type: boolean
24+
default: false
1125

1226
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
1327
permissions:
14-
contents: read
28+
contents: write
1529
pages: write
1630
id-token: write
1731

18-
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
19-
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
32+
# Allow only one concurrent deployment
2033
concurrency:
2134
group: "pages"
2235
cancel-in-progress: false
2336

2437
jobs:
25-
# Build Maven Site
26-
build:
38+
build-and-deploy:
2739
runs-on: ubuntu-latest
40+
environment:
41+
name: github-pages
42+
url: ${{ steps.deployment.outputs.page_url }}
2843
steps:
2944
- name: Checkout
3045
uses: actions/checkout@v6
46+
with:
47+
ref: ${{ github.event_name == 'release' && github.event.release.tag_name || github.ref }}
48+
fetch-depth: 0
3149

3250
- name: Set up JDK 17
3351
uses: actions/setup-java@v5
3452
with:
3553
java-version: '17'
3654
distribution: 'temurin'
3755

56+
- name: Determine version and paths
57+
id: version
58+
run: |
59+
if [[ "${{ github.event_name }}" == "release" ]]; then
60+
VERSION="${{ github.event.release.tag_name }}"
61+
VERSION="${VERSION#v}" # Remove 'v' prefix if present
62+
echo "version=$VERSION" >> $GITHUB_OUTPUT
63+
echo "is_release=true" >> $GITHUB_OUTPUT
64+
echo "deploy_path=$VERSION" >> $GITHUB_OUTPUT
65+
else
66+
# For main branch pushes
67+
CURRENT_VERSION=$(./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout)
68+
echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
69+
echo "is_release=false" >> $GITHUB_OUTPUT
70+
echo "deploy_path=snapshot" >> $GITHUB_OUTPUT
71+
fi
72+
3873
- name: Build Maven Site with Javadoc
3974
run: ./mvnw clean site -DskipTests -Dcheckstyle.skip=true
4075

76+
- name: Checkout gh-pages branch
77+
uses: actions/checkout@v6
78+
with:
79+
ref: gh-pages
80+
path: gh-pages
81+
continue-on-error: true
82+
83+
- name: Initialize gh-pages if needed
84+
run: |
85+
if [ ! -d "gh-pages" ]; then
86+
mkdir -p gh-pages
87+
cd gh-pages
88+
git init
89+
git checkout -b gh-pages
90+
fi
91+
92+
- name: Prepare versioned documentation
93+
run: |
94+
DEPLOY_PATH="${{ steps.version.outputs.deploy_path }}"
95+
96+
# Remove old version of this specific path (if exists)
97+
rm -rf "gh-pages/$DEPLOY_PATH"
98+
99+
# Copy new site to versioned path
100+
mkdir -p "gh-pages/$DEPLOY_PATH"
101+
cp -r target/site/* "gh-pages/$DEPLOY_PATH/"
102+
103+
# For releases, also update the root (latest)
104+
if [[ "${{ steps.version.outputs.is_release }}" == "true" ]] || [[ "${{ inputs.publish_as_latest }}" == "true" ]]; then
105+
# Preserve versioned folders when updating root
106+
find gh-pages -maxdepth 1 -type f -delete
107+
find gh-pages -maxdepth 1 -type d -name "[0-9]*" -prune -o -type d ! -name gh-pages ! -name snapshot ! -name .git -exec rm -rf {} + 2>/dev/null || true
108+
109+
# Copy site to root (latest release)
110+
cp -r target/site/* gh-pages/
111+
fi
112+
113+
# Copy version index page from template
114+
cp .github/templates/versions.html gh-pages/versions.html
115+
116+
- name: Update version list
117+
run: |
118+
cd gh-pages
119+
120+
# Find all version directories
121+
VERSIONS=$(find . -maxdepth 1 -type d -name "[0-9]*" | sed 's|./||' | sort -Vr)
122+
HAS_SNAPSHOT=$([ -d "snapshot" ] && echo "true" || echo "false")
123+
124+
# Generate version links
125+
VERSION_HTML=""
126+
127+
# Add latest (root) link
128+
VERSION_HTML+='<li><a href="./">Latest Release</a><span class="badge latest">latest</span></li>'
129+
130+
# Add snapshot if exists
131+
if [ "$HAS_SNAPSHOT" = "true" ]; then
132+
VERSION_HTML+='<li><a href="./snapshot/">Development (main branch)</a><span class="badge snapshot">snapshot</span></li>'
133+
fi
134+
135+
# Add versioned releases
136+
for v in $VERSIONS; do
137+
VERSION_HTML+="<li><a href=\"./$v/\">Version $v</a><span class=\"badge archived\">$v</span></li>"
138+
done
139+
140+
# Update the versions.html using the placeholder
141+
sed -i "s|<!-- VERSION_LIST_PLACEHOLDER -->|$VERSION_HTML|" versions.html
142+
143+
- name: Deploy to GitHub Pages
144+
run: |
145+
cd gh-pages
146+
git config user.name "github-actions[bot]"
147+
git config user.email "github-actions[bot]@users.noreply.github.com"
148+
git add -A
149+
git diff --staged --quiet || git commit -m "Deploy documentation: ${{ steps.version.outputs.deploy_path }}"
150+
git push origin gh-pages --force
151+
env:
152+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
153+
41154
- name: Setup Pages
42155
uses: actions/configure-pages@v5
43156

44157
- name: Upload artifact
45158
uses: actions/upload-pages-artifact@v4
46159
with:
47-
# Upload the generated site
48-
path: 'target/site'
160+
path: 'gh-pages'
49161

50-
# Deploy to GitHub Pages
51-
deploy:
52-
environment:
53-
name: github-pages
54-
url: ${{ steps.deployment.outputs.page_url }}
55-
runs-on: ubuntu-latest
56-
needs: build
57-
steps:
58162
- name: Deploy to GitHub Pages
59163
id: deployment
60164
uses: actions/deploy-pages@v4

0 commit comments

Comments
 (0)