Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
ff38ae169This file is pinned to the selected release. Download the original to open it in your design tool.
name: Software Documentation
on:
push:
branches:
- main
- master
paths:
- 'docs/**'
- '.github/workflows/documentation.yaml'
pull_request:
paths:
- 'docs/**'
- '.github/workflows/documentation.yaml'
workflow_dispatch:
env:
project_name: BeeLight
# Source directory for AsciiDoc files
docs_src_dir: docs/firmware
# Output directory for generated documentation
docs_out_dir: docs/generated
permissions:
contents: write
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
asciidoctor:
runs-on: ubuntu-latest
name: Build Documentation (AsciiDoc)
steps:
- name: Repository Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install AsciiDoctor
run: |
sudo apt-get update
sudo apt-get install -y asciidoctor ruby-asciidoctor-pdf
- name: Build AsciiDoc Documentation
run: |
set -e
mkdir -p ${{ env.docs_out_dir }}/pdf
cp -r docs/images ${{ env.docs_out_dir }}/images
# Build all .adoc files
echo "Processing AsciiDoc files..."
for File in ${{ env.docs_src_dir }}/*.adoc; do
if [ -f "$File" ]; then
base_name="$(basename ${File%.adoc})"
# Rename index to project-overview to avoid conflict with landing page
if [ "$base_name" = "index" ]; then
out_name="project-overview"
else
out_name="$base_name"
fi
echo " - Building ${out_name}..."
# Generate HTML (images referenced as images/ relative to output dir)
asciidoctor "$File" \
-a imagesdir=images \
-D "${{ env.docs_out_dir }}" \
-o "${out_name}.html"
# Generate PDF (images resolved relative to source file at build time)
asciidoctor-pdf "$File" \
-a imagesdir=../images \
-o "${{ env.docs_out_dir }}/pdf/${out_name}.pdf"
fi
done
# Create landing page
cat > ${{ env.docs_out_dir }}/index.html << 'LANDING'
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>BeeLight Firmware Documentation</title>
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
max-width: 1000px;
margin: 0 auto;
padding: 2rem;
line-height: 1.6;
background-color: #f5f5f5;
}
h1 { color: #333; border-bottom: 3px solid #e74c3c; padding-bottom: 0.5rem; }
h2 { color: #555; margin-top: 2rem; }
.header-info {
background: white; padding: 1.5rem; border-radius: 8px;
box-shadow: 0 2px 4px rgba(0,0,0,0.1); margin-bottom: 2rem;
}
.doc-list {
background: white; padding: 1.5rem; border-radius: 8px;
box-shadow: 0 2px 4px rgba(0,0,0,0.1); margin-bottom: 2rem;
}
.doc-item {
padding: 1rem; margin: 0.5rem 0;
background: #f8f9fa; border-left: 4px solid #e74c3c; border-radius: 4px;
}
.doc-item h3 { margin: 0 0 0.5rem 0; color: #e74c3c; }
.doc-item p { margin: 0.5rem 0; color: #666; font-size: 0.9rem; }
.doc-links { margin-top: 0.5rem; }
.doc-links a {
display: inline-block; margin-right: 1rem; padding: 0.3rem 0.8rem;
background: #e74c3c; color: white; text-decoration: none;
border-radius: 4px; font-size: 0.9rem;
}
.doc-links a:hover { background: #c0392b; }
.footer {
margin-top: 3rem; padding-top: 1rem;
border-top: 1px solid #ddd; color: #666; font-size: 0.9rem;
}
.badge {
display: inline-block; padding: 0.2rem 0.5rem; background: #3498db;
color: white; border-radius: 3px; font-size: 0.8rem; margin-left: 0.5rem;
}
</style>
</head>
<body>
<h1>BeeLight Firmware Documentation</h1>
<div class="header-info">
<p><strong>Battery-powered Zigbee Environmental Sensor</strong></p>
<p>BeeLight measures illuminance, temperature, air pressure, humidity, and battery voltage,
and transmits all values via Zigbee 3.0 to a coordinator (e.g. Home Assistant).</p>
<p>
<span class="badge">nRF54L15</span>
<span class="badge">Zigbee 3.0</span>
<span class="badge">Zephyr RTOS</span>
<span class="badge">nRF Connect SDK 2.9.2</span>
<span class="badge">BME688</span>
<span class="badge">APDS-9306</span>
</p>
</div>
<div class="doc-list">
<h2>Documentation</h2>
<div class="doc-item">
<h3>Project Overview</h3>
<p>Introduction to the BeeLight project: features, hardware revisions, and integration.</p>
<div class="doc-links">
<a href="project-overview.html">HTML</a>
<a href="pdf/project-overview.pdf">PDF</a>
</div>
</div>
<div class="doc-item">
<h3>Software Architecture</h3>
<p>ZBus event system, module overview, data flow, and power consumption strategy.</p>
<div class="doc-links">
<a href="architecture.html">HTML</a>
<a href="pdf/architecture.pdf">PDF</a>
</div>
</div>
<div class="doc-item">
<h3>Sensor Modules</h3>
<p>APDS-9306 light sensor, BME688 environmental sensor (incl. BSEC2), and battery monitoring.</p>
<div class="doc-links">
<a href="sensors.html">HTML</a>
<a href="pdf/sensors.pdf">PDF</a>
</div>
</div>
<div class="doc-item">
<h3>Zigbee Integration</h3>
<p>Zigbee clusters, ZCL attributes, BeeLight custom clusters (CO2, IAQ, VOC) and network behavior.</p>
<div class="doc-links">
<a href="zigbee.html">HTML</a>
<a href="pdf/zigbee.pdf">PDF</a>
</div>
</div>
<div class="doc-item">
<h3>Build & Configuration</h3>
<p>Prerequisites, west build commands, Kconfig options, and patch system.</p>
<div class="doc-links">
<a href="build.html">HTML</a>
<a href="pdf/build.pdf">PDF</a>
</div>
</div>
</div>
LANDING
# Append footer with dynamic timestamp
cat >> ${{ env.docs_out_dir }}/index.html << EOF
<div class="footer">
<p><strong>BeeLight Firmware</strong> – Documentation</p>
<p>Copyright © Daniel Kampert, 2025 | GNU General Public License v3.0</p>
<p>Generated: $(date -u +'%Y-%m-%d %H:%M:%S UTC')</p>
</div>
</body>
</html>
EOF
- name: Upload Pages Artifact
uses: actions/upload-pages-artifact@v3
with:
path: ${{ env.docs_out_dir }}
- name: Upload Docs Artifact
uses: actions/upload-artifact@v4
with:
name: docs-build
path: ${{ env.docs_out_dir }}
deploy-pages:
if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
needs:
- asciidoctor
runs-on: ubuntu-latest
name: Deploy to GitHub Pages
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
deploy:
if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' || contains(github.ref, 'refs/tags/'))
needs:
- asciidoctor
runs-on: ubuntu-latest
name: Deploy to Releases
steps:
- name: Repository Checkout
uses: actions/checkout@v4
- name: Download Artifacts
uses: actions/download-artifact@v4
with:
name: docs-build
path: docs-build
- name: Create release tarball
run: |
# Create renamed PDF copies for GitHub Releases (with -nightly suffix)
mkdir -p release_pdfs
for pdf_file in docs-build/pdf/*.pdf; do
[ -f "$pdf_file" ] || continue
base_name="$(basename ${pdf_file%.pdf})"
cp "$pdf_file" "release_pdfs/${base_name}-nightly.pdf"
done
# Create tarball of all generated docs
tar zcf ${{ env.project_name }}-Docs-nightly.tar.gz -C docs-build .
- name: Deploy to GitHub Releases
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh release view nightly 2>/dev/null || \
gh release create nightly \
--title "Nightly Documentation Build" \
--notes "Automatically generated documentation for ${{ env.project_name }}" \
--prerelease
mapfile -t pdf_files < <(find release_pdfs -name '*.pdf' 2>/dev/null)
gh release upload nightly \
"${{ env.project_name }}-Docs-nightly.tar.gz" \
"${pdf_files[@]}" --clobber