Allow building docs from different tags (#2218)

.github/workflows/documentation.yml

@@ -2,12 +2,33 @@ name: Documentation
 
 on:
   workflow_dispatch:
+    inputs:
+      esp-hal:
+        description: "esp-hal tag"
+        required: true
+      esp-wifi:
+        description: "esp-wifi tag"
+        required: true
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      packages: '[
+            { "name": "esp-hal",  "tag": "${{ github.event.inputs.esp-hal }}" },
+            { "name": "esp-wifi", "tag": "esp-wifi-${{ github.event.inputs.esp-wifi }}" }
+          ]'
+    steps:
+      - run: echo "Setup complete!"
   build:
+    needs: setup
+    strategy:
+      fail-fast: true
+      matrix:
+        packages: ${{ fromJson(needs.setup.outputs.packages) }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -16,21 +37,48 @@ jobs:
           default: true
           ldproxy: false
 
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          repository: esp-rs/esp-hal
+          ref: ${{ matrix.packages.tag }}
+
       - name: Build documentation
-        run: cargo xtask build-documentation --packages=esp-hal,esp-wifi
+        run: cargo xtask build-documentation --packages=${{ matrix.packages.name }}
 
       # 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 docs for ${{ matrix.packages.name }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.packages.name }}
+          path: "docs/${{ matrix.packages.name }}"
+
+  assemble:
+    needs: [setup, build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Prepare
+        run: mkdir docs
+      - name: Download all docs
+        uses: actions/download-artifact@v4
+        with:
+          path: "docs/"
+
+      - name: Create index.html
+        run: "cargo xtask build-documentation-index --packages=$(echo '${{ needs.setup.outputs.packages }}' | jq -r '[.[].name] | join(\",\")')"
+
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: "docs"
+          path: "docs/"
 
   deploy:
-    # Add a dependency to the build job:
-    needs: build
+    # Add a dependency to the assemble job:
+    needs: assemble
 
     # Grant GITHUB_TOKEN the permissions required to make a Pages deployment:
     permissions:

xtask/src/main.rs

@@ -22,6 +22,8 @@ use xtask::{
 
 #[derive(Debug, Parser)]
 enum Cli {
+    /// Build documentation for the specified chip.
+    BuildDocumentationIndex(BuildDocumentationArgs),
     /// Build documentation for the specified chip.
     BuildDocumentation(BuildDocumentationArgs),
     /// Build all examples for the specified chip.
@@ -163,6 +165,7 @@ fn main() -> Result<()> {
 
     match Cli::parse() {
         Cli::BuildDocumentation(args) => build_documentation(&workspace, args),
+        Cli::BuildDocumentationIndex(args) => build_documentation_index(&workspace, args),
         Cli::BuildExamples(args) => examples(&workspace, args, CargoAction::Build),
         Cli::BuildPackage(args) => build_package(&workspace, args),
         Cli::BuildTests(args) => tests(&workspace, args, CargoAction::Build),
@@ -360,7 +363,6 @@ fn tests(workspace: &Path, args: TestArgs, action: CargoAction) -> Result<()> {
 
 fn build_documentation(workspace: &Path, args: BuildDocumentationArgs) -> Result<()> {
     let output_path = workspace.join("docs");
-    let resources = workspace.join("resources");
 
     fs::create_dir_all(&output_path)
         .with_context(|| format!("Failed to create {}", output_path.display()))?;
@@ -373,6 +375,31 @@ fn build_documentation(workspace: &Path, args: BuildDocumentationArgs) -> Result
         );
     }
 
+    generate_index(workspace, &packages)?;
+
+    Ok(())
+}
+
+fn build_documentation_index(workspace: &Path, args: BuildDocumentationArgs) -> Result<()> {
+    let mut packages = HashMap::new();
+    for package in args.packages {
+        packages.insert(
+            package,
+            generate_documentation_meta_for_package(workspace, package, &args.chips)?,
+        );
+    }
+
+    generate_index(workspace, &packages)?;
+
+    Ok(())
+}
+
+fn generate_index(workspace: &Path, packages: &HashMap<Package, Vec<Value>>) -> Result<()> {
+    let output_path = workspace.join("docs");
+    let resources = workspace.join("resources");
+
+    fs::create_dir_all(&output_path)
+        .with_context(|| format!("Failed to create {}", output_path.display()))?;
     // Copy any additional assets to the documentation's output path:
     fs::copy(resources.join("esp-rs.svg"), output_path.join("esp-rs.svg"))
         .context("Failed to copy esp-rs.svg")?;
@@ -401,8 +428,6 @@ fn build_documentation_for_package(
 
     let version = xtask::package_version(workspace, package)?;
 
-    let mut metadata = Vec::new();
-
     for chip in chips {
         // Ensure that the package/chip combination provided are valid:
         validate_package_chip(&package, chip)?;
@@ -436,6 +461,25 @@ fn build_documentation_for_package(
                 output_path.display()
             )
         })?;
+    }
+
+    Ok(generate_documentation_meta_for_package(
+        workspace, package, chips,
+    )?)
+}
+
+fn generate_documentation_meta_for_package(
+    workspace: &Path,
+    package: Package,
+    chips: &[Chip],
+) -> Result<Vec<Value>> {
+    let version = xtask::package_version(workspace, package)?;
+
+    let mut metadata = Vec::new();
+
+    for chip in chips {
+        // Ensure that the package/chip combination provided are valid:
+        validate_package_chip(&package, chip)?;
 
         // Build the context object required for rendering this particular build's
         // information on the documentation index: