From 6d96810c561d370343b69e8d8bf7f3286807d9b8 Mon Sep 17 00:00:00 2001 From: Scott Mabin Date: Thu, 26 Sep 2024 01:55:54 -0700 Subject: [PATCH] Allow building docs from different tags (#2218) --- .github/workflows/documentation.yml | 56 ++++++++++++++++++++++++++--- xtask/src/main.rs | 50 ++++++++++++++++++++++++-- 2 files changed, 99 insertions(+), 7 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 0e4e1d99853..43b701b345d 100644 --- a/.github/workflows/documentation.yml +++ b/.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: diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 262bdd2102d..d5d5d013406 100644 --- a/xtask/src/main.rs +++ b/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>) -> 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> { + 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: