From ec4185fcc7ccae39e6eadae090d5fb5f140dbaa5 Mon Sep 17 00:00:00 2001 From: Kathryn Baldauf Date: Wed, 4 Jun 2025 14:59:57 -0700 Subject: [PATCH] Publish docs github action (#9) Signed-off-by: Kathryn Baldauf --- .github/workflows/build.yml | 1 + .github/workflows/common.yml | 37 ++++++++++++++++++++++++---- .github/workflows/docs-release.yml | 39 ++++++++++++++++++++++++++++++ .github/workflows/release.yml | 2 ++ Makefile | 19 ++++++--------- scripts/make-docs.sh | 20 +++++++-------- 6 files changed, 92 insertions(+), 26 deletions(-) create mode 100644 .github/workflows/docs-release.yml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 7bf5a31e..18e1d9c6 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -18,3 +18,4 @@ jobs: permissions: contents: read packages: read + pages: write diff --git a/.github/workflows/common.yml b/.github/workflows/common.yml index 2055e649..b3b7e345 100644 --- a/.github/workflows/common.yml +++ b/.github/workflows/common.yml @@ -38,19 +38,19 @@ jobs: # TODO [launch]: TEMPORARILY we need to exclude these files since we had to modify them to add # the github token for pulling the private repos. if ! git diff --quiet -- . ':(exclude)Package.swift' ':(exclude)Package.resolved' ':(exclude)Protobuf.Makefile'; then echo "The following files require formatting or license header updates:\n$(git diff --name-only)" ; false ; fi - env: CURRENT_SDK: y - CONTAINERIZATION_REPO: https://${{ secrets.REPO_READ }}@github.com/apple/containerization.git + CONTAINERIZATION_REPO: https://${{ secrets.REPO_READ }}@github.com/apple/containerization.git - name: Set build configuration run: | echo "BUILD_CONFIGURATION=debug" >> $GITHUB_ENV if [ ${{ inputs.release }} == true ]; then echo "BUILD_CONFIGURATION=release" >> $GITHUB_ENV fi - - name: Make the container project + - name: Make the container project and docs run: | - make container dsym + make container dsym docs + tar cfz _site.tgz _site env: DEVELOPER_DIR: "/Applications/Xcode_16.3.app/Contents/Developer" CURRENT_SDK: y @@ -71,8 +71,35 @@ jobs: DEVELOPER_DIR: "/Applications/Xcode_16.3.app/Contents/Developer" CURRENT_SDK: y CONTAINERIZATION_REPO: https://${{ secrets.REPO_READ }}@github.com/apple/containerization.git - - name: Save artifacts + - name: Save documentation artifact + uses: actions/upload-artifact@v4 + with: + name: api-docs + path: "./_site.tgz" + retention-days: 14 + - name: Save package artifacts uses: actions/upload-artifact@v4 with: name: container-package path: ${{ github.workspace }}/outputs + uploadPages: + # Separate upload step required because upload-pages-artifact needs + # gtar which is not on the macOS runner. + name: Upload artifact for GitHub Pages + needs: buildAndTest + timeout-minutes: 5 + runs-on: ubuntu-latest + steps: + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Download a single artifact + uses: actions/download-artifact@v4 + with: + name: api-docs + - name: Add API docs to documentation + run: | + tar xfz _site.tgz + - name: Upload Artifact + uses: actions/upload-pages-artifact@v3 + with: + path: "./_site" diff --git a/.github/workflows/docs-release.yml b/.github/workflows/docs-release.yml new file mode 100644 index 00000000..03063abc --- /dev/null +++ b/.github/workflows/docs-release.yml @@ -0,0 +1,39 @@ +# Manual workflow for releasing docs ad-hoc. Workflow can only be run for main or release branches. +# Workflow does NOT publish a release of container. +name: Deploy application website +on: + workflow_dispatch: + +jobs: + checkBranch: + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'ref/heads/release') + steps: + - name: Branch validation + run: echo "Branch ${{ github.ref_name }} is allowed" + + buildSite: + name: Build application website + needs: checkBranch + uses: ./.github/workflows/common.yml + secrets: inherit + permissions: + contents: read + packages: write + pages: write + + deployDocs: + runs-on: ubuntu-latest + needs: [checkBranch, buildSite] + permissions: + contents: read + pages: write + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6a193e79..449007b9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -15,6 +15,7 @@ jobs: permissions: contents: read packages: read + pages: write release: name: Publish release timeout-minutes: 30 @@ -23,6 +24,7 @@ jobs: permissions: contents: write packages: read + pages: write steps: - name: Download artifacts uses: actions/download-artifact@v4 diff --git a/Makefile b/Makefile index 69972303..2011a244 100644 --- a/Makefile +++ b/Makefile @@ -165,19 +165,16 @@ check-licenses: .PHONY: serve-docs serve-docs: - @echo 'to browse: open http://localhost:8000/documentation/' - @python3 -m http.server --bind 127.0.0.1 --directory ./api-docs + @echo 'to browse: open http://127.0.0.1:8000/documentation/' + @python3 -m http.server --bind 127.0.0.1 --directory ./_site .PHONY: docs -docs: - @echo Updating documentation... - @rm -rf ./api-docs - @mkdir -p ./api-docs - @if [ -z "$${DOCS_BASE_PATH}" ] ; then \ - scripts/make-docs.sh ./api-docs ; \ - else \ - scripts/make-docs.sh ./api-docs $${DOCS_BASE_PATH} ; \ - fi +docs: _site + +_site: + @echo Updating API documentation... + rm -rf $@ + @scripts/make-docs.sh $@ .PHONY: cleancontent cleancontent: diff --git a/scripts/make-docs.sh b/scripts/make-docs.sh index fca2eaf2..0664afbe 100755 --- a/scripts/make-docs.sh +++ b/scripts/make-docs.sh @@ -19,17 +19,17 @@ if [ ! -z "${CURRENT_SDK}" ] ; then fi opts+=("--allow-writing-to-directory" "$1") opts+=("generate-documentation") -opts+=("--target" "Build") -opts+=("--target" "Client") -opts+=("--target" "DNSServer") -opts+=("--target" "ImagesService") -opts+=("--target" "LogSupport") -opts+=("--target" "NetworkService") -opts+=("--target" "Persistence") -opts+=("--target" "Plugin") -opts+=("--target" "SandboxService") +opts+=("--target" "ContainerSandboxService") +opts+=("--target" "ContainerNetworkService") +opts+=("--target" "ContainerImagesService") +opts+=("--target" "ContainerClient") +opts+=("--target" "ContainerBuild") +opts+=("--target" "ContainerLog") +opts+=("--target" "ContainerPersistence") +opts+=("--target" "ContainerPlugin") +opts+=("--target" "CVersion") +opts+=("--target" "ContainerXPC") opts+=("--target" "TerminalProgress") -opts+=("--target" "XPCSupport") opts+=("--output-path" "$1") opts+=("--disable-indexing") opts+=("--transform-for-static-hosting")