Skip to content

Commit 44ba26e

Browse files
itowlsonitowlson
authored
Merge pull request #226 from vados-cosmonic/fix(ci)=run-mdbook-on-prs
feat(ci): run mdbook on pull requests
2 parents 7f7681a + 9267bbb commit 44ba26e

File tree

5 files changed

+224
-89
lines changed

5 files changed

+224
-89
lines changed

‎.github/actions/mdbook/action.yml

+98
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
name: mdbook
2+
3+
description: |
4+
Run the mdbook build, optionally outputting a pages artifact
5+
6+
inputs:
7+
publish-pages-artifact:
8+
type: boolean
9+
required: false
10+
default: false
11+
description: |
12+
Whether to publish a pages artifact
13+
14+
publish-domain:
15+
type: string
16+
required: false
17+
default: "component-model.bytecodealliance.org"
18+
description: |
19+
Path to which to store the artifac
20+
21+
mdbook-version:
22+
type: string
23+
required: false
24+
default: "0.4.21"
25+
description: |
26+
Version of mdbook to use (ex. '0.4.21')
27+
28+
mdbook-alerts-version:
29+
type: string
30+
required: false
31+
default: "0.6.7"
32+
description: |
33+
Version of mdbook-alerts to use (ex. '0.6.7')
34+
35+
mdbook-linkcheck-version:
36+
type: string
37+
required: false
38+
default: "0.7.7"
39+
description: |
40+
Version of mdbook-linkcheck to use (ex. '0.7.7')
41+
42+
runs:
43+
using: composite
44+
steps:
45+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
46+
47+
- uses: extractions/setup-just@v2
48+
49+
- uses: taiki-e/cache-cargo-install-action@4d586f211d9b0bca9e7b59e57e2a0febf36c0929 # v2.1.1
50+
with:
51+
tool: "mdbook@${{ inputs.mdbook-version }}"
52+
53+
- uses: taiki-e/cache-cargo-install-action@4d586f211d9b0bca9e7b59e57e2a0febf36c0929 # v2.1.1
54+
with:
55+
tool: "mdbook-alerts@${{ inputs.mdbook-alerts-version }}"
56+
57+
- uses: taiki-e/cache-cargo-install-action@4d586f211d9b0bca9e7b59e57e2a0febf36c0929 # v2.1.1
58+
with:
59+
tool: "mdbook-linkcheck@${{ inputs.mdbook-linkcheck-version }}"
60+
61+
- name: Setup Python
62+
uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
63+
with:
64+
python-version: '3.13'
65+
66+
- name: Build with mdBook
67+
shell: bash
68+
id: book-build
69+
env:
70+
PUBLISH_DOMAIN: ${{ inputs.publish-domain }}
71+
run: |
72+
just build-book
73+
echo "output-path=$(just print-book-dir)" >> $GITHUB_OUTPUT
74+
75+
- name: Generate sitemap
76+
shell: bash
77+
run: |
78+
just build-sitemap
79+
80+
- name: Ensure publish-domain was provided
81+
if: ${{ inputs.publish-pages-artifact }}
82+
shell: bash
83+
run: |
84+
if [ -z "${{ inputs.publish-domain }}" ]; then
85+
echo "[error] publish-domain input is required when publishing";
86+
exit 1;
87+
fi
88+
89+
- name: Setup Pages
90+
if: ${{ inputs.publish-pages-artifact }}
91+
id: pages
92+
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
93+
94+
- name: Upload artifact
95+
if: ${{ inputs.publish-pages-artifact }}
96+
uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
97+
with:
98+
path: ${{ steps.book-build.outputs.output-path }}

‎.github/workflows/deploy.yml

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Deploy mdBook site to Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
workflow_dispatch:
9+
inputs:
10+
ref:
11+
required: false
12+
type: string
13+
default: main
14+
description: |
15+
The git ref to deploy (ex. 'main', 'branch', '<commit sha>')
16+
17+
publish-domain:
18+
required: false
19+
type: string
20+
default: "component-model.bytecodealliance.org"
21+
description: |
22+
The domain to which to publish (ex. 'component-model.bytecodealliance.org')
23+
24+
permissions:
25+
contents: read
26+
pages: write
27+
id-token: write
28+
29+
concurrency:
30+
group: "pages"
31+
cancel-in-progress: false
32+
33+
env:
34+
MDBOOK_VERSION: 0.4.21
35+
MDBOOK_ALERTS_VERSION: 0.6.7
36+
MDBOOK_LINKCHECK_VERSION: 0.7.7
37+
ARTIFACT_PATH: ./component-model/book/html
38+
39+
jobs:
40+
build:
41+
runs-on: ubuntu-latest
42+
steps:
43+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
44+
with:
45+
ref: ${{ inputs.ref || 'main' }}
46+
47+
- name: build mdbook
48+
uses: ./.github/actions/mdbook
49+
with:
50+
publish-pages-artifact: true
51+
publish-domain: ${{ inputs.publish-domain || 'component-model.bytecodealliance.org' }}
52+
53+
deploy:
54+
if: ${{ github.repository_owner == 'bytecodealliance' }}
55+
runs-on: ubuntu-latest
56+
needs:
57+
- build
58+
environment:
59+
name: github-pages
60+
url: ${{ steps.deployment.outputs.page_url }}
61+
steps:
62+
- name: Deploy to GitHub Pages
63+
id: deployment
64+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

‎.github/workflows/mdbook.yml

+6-82
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,15 @@
1-
# Sample workflow for building and deploying a mdBook site to GitHub Pages
2-
#
3-
# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
4-
#
5-
name: Deploy mdBook site to Pages
1+
name: mdbook
62

73
on:
8-
# Runs on pushes targeting the default branch
9-
push:
10-
branches: ["main"]
11-
12-
# Allows you to run this workflow manually from the Actions tab
13-
workflow_dispatch:
14-
15-
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
16-
permissions:
17-
contents: read
18-
pages: write
19-
id-token: write
20-
21-
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
22-
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
23-
concurrency:
24-
group: "pages"
25-
cancel-in-progress: false
26-
27-
env:
28-
MDBOOK_VERSION: 0.4.21
29-
MDBOOK_ALERTS_VERSION: 0.6.7
30-
MDBOOK_LINKCHECK_VERSION: 0.7.7
31-
PUBLISH_DOMAIN: component-model.bytecodealliance.org
32-
ARTIFACT_PATH: ./component-model/book/html
4+
pull_request:
335

346
jobs:
357
build:
368
runs-on: ubuntu-latest
379
steps:
38-
- uses: actions/checkout@v3
39-
- name: Install mdBook
40-
run: |
41-
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
42-
rustup update
43-
cargo install --version ${{ env.MDBOOK_VERSION }} mdbook
44-
cargo install --version ${{ env.MDBOOK_ALERTS_VERSION }} mdbook-alerts
45-
cargo install --version ${{ env.MDBOOK_LINKCHECK_VERSION }} mdbook-linkcheck
10+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
4611

47-
- name: Build with mdBook
48-
run: mdbook build component-model
49-
50-
- name: Setup Python
51-
uses: actions/setup-python@v5
12+
- name: build mdbook
13+
uses: ./.github/actions/mdbook
5214
with:
53-
python-version: '3.13'
54-
55-
# Ensure the build generated properly
56-
- name: Ensure build outputs are present
57-
shell: bash
58-
run: |
59-
if [[ ! -f "${{ env.ARTIFACT_PATH }}/index.html" ]]; then
60-
echo "[error] index.html @ [${{ env.ARTIFACT_PATH }}] is missing. Build or path misconfigured";
61-
exit 1;
62-
fi
63-
64-
- name: Generate sitemap
65-
shell: bash
66-
run: |
67-
cd ${{ env.ARTIFACT_PATH }}
68-
python3 ../../../scripts/generate_sitemap.py --domain "component-model.bytecodealliance.org" --higher-priority "design" --output-path sitemap.xml
69-
cd ../../../
70-
71-
- name: Setup Pages
72-
id: pages
73-
uses: actions/configure-pages@v3
74-
75-
- name: Upload artifact
76-
uses: actions/upload-pages-artifact@v3
77-
with:
78-
path: ${{ env.ARTIFACT_PATH }}
79-
80-
# Deployment job
81-
deploy:
82-
if: ${{ github.repository_owner == 'bytecodealliance' }}
83-
environment:
84-
name: github-pages
85-
url: ${{ steps.deployment.outputs.page_url }}
86-
runs-on: ubuntu-latest
87-
needs: build
88-
steps:
89-
- name: Deploy to GitHub Pages
90-
id: deployment
91-
uses: actions/deploy-pages@v4
15+
publish-pages-artifact: true

‎justfile

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
just := env_var_or_default("JUST", "just")
2+
just_dir := env_var_or_default("JUST_DIR", justfile_directory())
3+
4+
python := env_var_or_default("PYTHON", "python3")
5+
cargo := env_var_or_default("CARGO", "cargo")
6+
mdbook := env_var_or_default("MDBOOK", "mdbook")
7+
8+
publish_domain := env_var_or_default("PUBLISH_DOMAIN", "component-model.bytecodealliance.org")
9+
10+
scripts_dir := env_var_or_default("SCRIPTS_DIR", "scripts")
11+
12+
sitemap_output_path := env_var_or_default("SITEMAP_OUTPUT_PATH", absolute_path("./component-model/book/html/sitemap.xml"))
13+
book_output_dir := env_var_or_default("BOOK_OUTPUT_DIR", "./component-model/book/html")
14+
15+
@_default:
16+
{{just}} --list
17+
18+
# Print the directory the book is/would be output to
19+
[group('meta')]
20+
@print-book-dir:
21+
echo -n {{book_output_dir}}
22+
23+
# Build the book
24+
[group('build')]
25+
@build-book:
26+
{{mdbook}} build component-model
27+
28+
# Build the sitemap
29+
[group('build')]
30+
@build-sitemap:
31+
{{python}} {{scripts_dir}}/generate_sitemap.py --domain "{{publish_domain}}" --higher-priority "design" --output-path {{sitemap_output_path}}
32+
if [ ! -f "{{book_output_dir}}/index.html" ]; then \
33+
echo "[error] index.html @ [{{book_output_dir}}] is missing. Build or path misconfigured"; \
34+
exit 1; \
35+
fi

‎scripts/generate_sitemap.py

+21-7
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
import os
22
from urllib.parse import urljoin
33
from datetime import datetime
4+
from pathlib import Path
5+
46
import argparse
57

6-
def parse_summary():
8+
def parse_summary(summary_file_path):
79
"""Parse URLs from the SUMMARY.md file."""
8-
with open("../../src/SUMMARY.md", "r") as file:
10+
with open(summary_file_path, "r") as file:
911
for line in file:
1012
if "](" in line:
1113
url = line.split("](")[1].split(")")[0]
@@ -23,10 +25,10 @@ def determine_priority(url_path, higher_priority_section):
2325
else:
2426
return "0.5" # All other pages
2527

26-
def generate_sitemap(domain, output_path, higher_priority_section):
28+
def generate_sitemap(domain, output_path, summary_file_path, higher_priority_section):
2729
"""Generate a sitemap XML file from SUMMARY.md structure."""
2830
domain = "https://" + domain
29-
urls = parse_summary() # Add base URL to the list of URLs
31+
urls = parse_summary(summary_file_path) # Add base URL to the list of URLs
3032
urls = [""] + list(urls)
3133

3234
sitemap = '<?xml version="1.0" encoding="UTF-8"?>\n'
@@ -48,11 +50,23 @@ def generate_sitemap(domain, output_path, higher_priority_section):
4850
with open(output_path, "w") as file:
4951
file.write(sitemap)
5052

53+
DEFAULT_SUMMARY_MD_PATH = (Path(__file__).parent / "../component-model/src/SUMMARY.md").resolve()
54+
DEFAULT_SITEMAP_XML_PATH = (Path(__file__).parent / "../component-model/book/html/sitemap.sml").resolve()
55+
5156
if __name__ == "__main__":
5257
parser = argparse.ArgumentParser(description="Generate a sitemap for mdBook")
53-
parser.add_argument("-d", "--domain", required=True, help="Domain for the mdBook site (e.g., component-model.bytecodealliance.org)")
54-
parser.add_argument("-o", "--output-path", default="sitemap.xml", help="Output path for the sitemap file")
58+
parser.add_argument("-d", "--domain", required=True, help="Domain for the mdBook site (e.g., 'component-model.bytecodealliance.org')")
59+
parser.add_argument("-o", "--output-path", default=DEFAULT_SITEMAP_XML_PATH, help="Output path for the sitemap file")
60+
parser.add_argument("-s", "--summary-md-path", default=DEFAULT_SUMMARY_MD_PATH, help="Path to SUMMARY.md")
5561
parser.add_argument("-p", "--higher-priority", help="Subsection path (e.g., 'design') to assign a higher priority of 0.8")
5662
args = parser.parse_args()
5763

58-
generate_sitemap(args.domain, args.output_path, args.higher_priority)
64+
summary_file_path = Path(args.summary_md_path).resolve()
65+
if not summary_file_path.exists():
66+
raise FileNotFoundError(f"failed to find summary file [{summary_file_path}]")
67+
68+
output_path = Path(args.output_path).resolve()
69+
if not output_path.parent.exists():
70+
raise FileNotFoundError(f"failed to find output dir [{output_path.parent}]")
71+
72+
generate_sitemap(args.domain, output_path, summary_file_path, args.higher_priority)

0 commit comments

Comments
 (0)