Skip to content

Commit

Permalink
Add a workflow to build and deploy esp-hal documentation to GitHub …
Browse files Browse the repository at this point in the history 
…Pages (#1248)

* update workflow

* Format `index.html`, update the URLs, add favicon, various other minor tweaks

* Move script into `.github/scripts`, add the package version to documentation path

* Split the building and deployment of documentation into its own workflow

---------

Co-authored-by: Kirill Mikhailov <[email protected]>
  • Loading branch information
@jessebraham @playfulFence
jessebraham and playfulFence authored Mar 7, 2024
1 parent e65951c commit 518e995
Show file tree
Hide file tree
Showing 5 changed files with 225 additions and 0 deletions.
25 changes: 25 additions & 0 deletions .github/scripts/build_docs.sh
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
#!/usr/bin/env bash

set -euo pipefail

# Extract the package version from `esp-hal` (using arcane methods):
PKG_VERSION=$(
cargo metadata --format-version=1 --no-deps --manifest-path=esp-hal/Cargo.toml \
| jq -r '.packages[] | select(.name=="esp-hal") | .version'
)

# Build the documentation for each supported cheap, namespacing by
# package version and chip:
CHIPS=("esp32" "esp32c2" "esp32c3" "esp32c6" "esp32h2" "esp32p4" "esp32s2" "esp32s3")

for CHIP in "${CHIPS[@]}"; do
cargo xtask build-documentation \
--output-path="docs/$PKG_VERSION"/"$CHIP"/ \
esp-hal \
"$CHIP"
done

# Copy any additional resources (such as the index and our logo)
# to the location of the built documentation as well:
cp resources/esp-rs.svg docs/
cp resources/index.html docs/
50 changes: 50 additions & 0 deletions .github/workflows/documentation.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
name: Documentation

on:
workflow_dispatch:

env:
CARGO_TERM_COLOR: always

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: esp-rs/[email protected]
with:
default: true
ldproxy: false

- name: Build documentation
run: ./.github/scripts/build_docs.sh

# https://github.com/actions/deploy-pages/issues/303#issuecomment-1951207879
- name: Remove problematic '.lock' files
run: find docs -name ".lock" -exec rm -f {} \;

- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v3
with:
path: "docs"

deploy:
# Add a dependency to the build job:
needs: build

# Grant GITHUB_TOKEN the permissions required to make a Pages deployment:
permissions:
pages: write # to deploy to Pages
id-token: write # to verify the deployment originates from an appropriate source

# Deploy to the github-pages environment:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}

# Specify runner + deployment step:
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
4 changes: 4 additions & 0 deletions resources/.prettierrc.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"printWidth": 100,
"tabWidth": 2
}
4 changes: 4 additions & 0 deletions resources/esp-rs.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
142 changes: 142 additions & 0 deletions resources/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />

<title>esp-rs docs</title>

<link rel="icon" href="esp-rs.svg" />
<link
href="https://fonts.googleapis.com/css2?family=Fira+Sans:wght@400;500&display=swap"
rel="stylesheet"
/>
<link
href="https://fonts.googleapis.com/css2?family=Source+Serif+4:ital,wght@0,400;0,600;1,400;1,600&display=swap"
rel="stylesheet"
/>

<style>
body {
background-color: rgb(53, 53, 53);
font-family: "Fira Sans", sans-serif;
color: white;
margin: 0;
padding: 40px 20px;
display: flex;
height: 100vh;
width: 100vw;
justify-content: center;
box-sizing: border-box;
}
.logo {
text-align: center;
margin-bottom: 50px;
font-size: 2em;
font-weight: 500;
}
.logo img {
width: 100px;
height: auto;
margin-bottom: 20px;
}
.content {
width: 900px;
}
.crate {
display: flex;
align-items: center;
padding: 10px;
border-bottom: 2px solid #454444;
}
.crate-description {
flex: 1;
font-family: "Source Serif 4", serif;
color: #c0c0c0;
text-align: center;
}
.crate-name {
color: #d6991d;
width: 120px;
}
/* Ensure the link color does not change after being clicked */
.crate-name a:link,
.crate-name a:visited,
.crate-name a:hover,
.crate-name a:active,
.crate-name a:focus {
color: #d6991d;
}
.crate-version {
color: #c0c0c0;
text-align: center;
width: 120px;
}

@media screen and (min-height: 650px) {
body {
align-items: center;
}
}
</style>
</head>
<body>
<div class="content">
<div class="logo">
<img src="esp-rs.svg" alt="esp-rs logo" />
<div>esp-rs docs</div>
</div>

<!-- TODO: Generate the index from a template, rather than hard-coding
the package version in the URL and '.crate-version' span. -->

<div class="crate">
<span class="crate-name"><a href="0.15.0/esp32/esp_hal/index.html">esp32</a></span>
<span class="crate-description">esp-hal (targeting ESP32)</span>
<span class="crate-version">0.15.0</span>
</div>

<div class="crate">
<span class="crate-name"><a href="0.15.0/esp32c2/esp_hal/index.html">esp32c2</a></span>
<span class="crate-description">esp-hal (targeting ESP32-C2)</span>
<span class="crate-version">0.15.0</span>
</div>

<div class="crate">
<span class="crate-name"><a href="0.15.0/esp32c3/esp_hal/index.html">esp32c3</a></span>
<span class="crate-description">esp-hal (targeting ESP32-C3)</span>
<span class="crate-version">0.15.0</span>
</div>

<div class="crate">
<span class="crate-name"><a href="0.15.0/esp32c6/esp_hal/index.html">esp32c6</a></span>
<span class="crate-description">esp-hal (targeting ESP32-C6)</span>
<span class="crate-version">0.15.0</span>
</div>

<div class="crate">
<span class="crate-name"><a href="0.15.0/esp32h2/esp_hal/index.html">esp32h2</a></span>
<span class="crate-description">esp-hal (targeting ESP32-H2)</span>
<span class="crate-version">0.15.0</span>
</div>

<div class="crate">
<span class="crate-name"><a href="0.15.0/esp32p4/esp_hal/index.html">esp32p4</a></span>
<span class="crate-description">esp-hal (targeting ESP32-P4)</span>
<span class="crate-version">0.15.0</span>
</div>

<div class="crate">
<span class="crate-name"><a href="0.15.0/esp32s2/esp_hal/index.html">esp32s2</a></span>
<span class="crate-description">esp-hal (targeting ESP32-S2)</span>
<span class="crate-version">0.15.0</span>
</div>

<div class="crate">
<span class="crate-name"><a href="0.15.0/esp32s3/esp_hal/index.html">esp32s3</a></span>
<span class="crate-description">esp-hal (targeting ESP32-S3)</span>
<span class="crate-version">0.15.0</span>
</div>
</div>
</body>
</html>

0 comments on commit 518e995

Please sign in to comment.