Publish docs github action (#9)

Signed-off-by: Kathryn Baldauf <k_baldauf@apple.com>

.github/workflows/build.yml

@@ -18,3 +18,4 @@ jobs:
     permissions:
       contents: read
       packages: read
+      pages: write

.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"

.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

.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

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:

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")