Add docc static site GitHub Pages deployment action (#89)

* Skip the index fixing step

* Explicitly set the hosting base path

* Remove duplicate docc archiving scripts

* Add step to swap index.html

* Index file cleanup

* Copy theme-settings file

* Limit deployments to main branch pushes

* Make script reusable

* Add link to guide

* Limit pages deployments to main pushes

Author: andrewjl-mux

.github/workflows/docc-on-release.yml

@@ -41,10 +41,10 @@ jobs:
           devdocs_bucket: upload-swift
           sdk_semantic_version: ${{ steps.version.outputs.version_name }}
         run: |
-          .github/workflows/scripts/create-docc-archive.sh
+          ./scripts/create-docc-archive.sh
       - name: Update the docs AWS bucket
         run: |
-          .github/workflows/scripts/upload-to-dev-docs.sh upload-swift ${{ steps.version.outputs.version_name }}
+          ./scripts/upload-to-dev-docs.sh upload-swift ${{ steps.version.outputs.version_name }}
       - name: Update the devdocs site
         run: |
           echo "${{ secrets.DOCS_REPO_PAT }}" | gh auth login --with-token

.github/workflows/docc-static-site-deployment.yml

@@ -0,0 +1,34 @@
+name: Docc Static Site Deployment
+on:
+  push:
+    branches: ["main"]
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+jobs:
+  deploy-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: sersoft-gmbh/swifty-docs-action@v2
+        with:
+          output: docs
+          use-xcodebuild: true
+          xcodebuild-scheme: MuxUploadSDK
+          xcodebuild-destination: generic/platform=iOS
+          transform-for-static-hosting: true
+          hosting-base-path: swift-upload-sdk
+      - name: Post Process Docc Archive
+        run: ./scripts/post-process-docc-archive-for-github-pages.sh swift-upload-sdk muxuploadsdk
+      - uses: actions/upload-pages-artifact@v1
+        with:
+          path: docs
+      - uses: actions/deploy-pages@v1.2.3
+        id: deployment

.github/workflows/scripts/create-docc-archive.sh

@@ -6,6 +6,9 @@ Each video is uploaded to an authenticated [upload URL created by a trusted back
 ## Usage
 To use this SDK, you'll need to add it as a dependency using either Swift Package Manager or Cocoapods.
 
+## Documentation
+A getting started guide can be found [here](https://docs.mux.com/guides/video/upload-video-directly-from-ios-or-ipados).
+
 ### Server-Side: Create a Direct Upload
 
 If you haven't yet done so, you must create an [access token](https://docs.mux.com/guides/system/make-api-requests#http-basic-auth) to complete these steps.

.github/workflows/scripts/index.html.template

@@ -2,26 +2,18 @@
 
 readonly XCODE=$(xcodebuild -version | grep Xcode | cut -d " " -f2)
 
-readonly TOP_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )/.." && pwd )"
+#readonly TOP_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )/.." && pwd )"
+readonly TOP_DIR=`pwd`
 readonly BUILD_DIR="${TOP_DIR}/.build"
 readonly DOCUMENTATION_DIR="${BUILD_DIR}/docs"
-readonly XCCONFIG_DIR="${TOP_DIR}/FrameworkXCConfigs/"
-
-readonly PROJECT_NAME="SwiftUploadSDKExample"
-readonly PROJECT_PATH="${TOP_DIR}/Example/SwiftUploadSDKExample/${PROJECT_NAME}.xcodeproj"
-readonly SCHEME="MuxUploadSDK"
-readonly BUILD_CONFIGURATION="Release"
-readonly BASE_XCCONFIG_FILENAME="Base"
-readonly XCCONFIG_FILENAME="Release-Production"
 
+readonly SCHEME=${target_scheme}
 readonly DOCC_ARCHIVE_NAME="${SCHEME}.doccarchive"
 readonly DOCC_ARCHIVE_PATH="${BUILD_DIR}/${DOCC_ARCHIVE_NAME}"
 
-echo "YO PROJECT PATH IS ${PROJECT_PATH}"
-
 # Subdirectory of the devdocs S3 bucket where SDK static docs are stored
 # in a directory corresponding to the SDKs version. Ex: "${DOCS_ROOT_DIR}/1.0.0"
-readonly DOCS_ROOT_DIR="spaces-ios"
+readonly DOCS_ROOT_DIR=${devdocs_bucket}
 
 if ! command -v xcbeautify &> /dev/null
 then
@@ -35,19 +27,15 @@ rm -rf ${BUILD_DIR}
 
 echo "▸ Using Xcode Version: ${XCODE}"
 
-echo "▸ Building Documentation Catalog for ${SCHEME} located in ${PROJECT_PATH}"
+echo "▸ Building Documentation Catalog for ${SCHEME}"
 
 mkdir -p $DOCUMENTATION_DIR
 
-expanded_xcconfig_path="${XCCONFIG_DIR}/${XCCONFIG_FILENAME}.xcconfig"
-
-# -xcconfig $expanded_xcconfig_path \
-xcodebuild docbuild -project $PROJECT_PATH \
-                    -scheme $SCHEME \
-                    -configuration $BUILD_CONFIGURATION \
+xcodebuild docbuild -scheme $SCHEME \
                     -destination 'generic/platform=iOS' \
                     -sdk iphoneos \
-                    -derivedDataPath "${DOCUMENTATION_DIR}" | xcbeautify \
+                    -derivedDataPath "${DOCUMENTATION_DIR}" \
+                    | xcbeautify 
 
 cd ${BUILD_DIR}
 
@@ -58,23 +46,15 @@ docc_built_archive_path=$(find docs -type d -name "${DOCC_ARCHIVE_NAME}")
 
 if [ -z "${docc_built_archive_path}" ]
 then
-echo -e "\033[1;31m ERROR: Failed to locate Documentation Archive \033[0m"
+    echo -e "\033[1;31m ERROR: Failed to locate Documentation Archive \033[0m"
     exit 1
 else
     echo "▸ Located documentation archive at ${docc_built_archive_path}"
-    mv ${docc_built_archive_path} ${BUILD_DIR}
+    #mv ${docc_built_archive_path} ${BUILD_DIR}
+    cp -r ${docc_built_archive_path} ${BUILD_DIR}
     zip -qry "${DOCC_ARCHIVE_NAME}.zip" "${DOCC_ARCHIVE_NAME}"
 fi
 
-expanded_base_xcconfig_path="${XCCONFIG_DIR}/${BASE_XCCONFIG_FILENAME}.xcconfig"
-
-# Locates the SDK marketing version and extracts it to a variable
-#
-# Uses the substitute (s) command to lines containing 'MARKETING_VERSION = ' 
-# substring then captures everything on that line after the subscript (\(.*\)) 
-# then prints the first such match
-sdk_semantic_version="$(sed -n 's/MARKETING_VERSION = \(.*\)/\1/p' $expanded_base_xcconfig_path)"
-
 # When deploying a new version the contents of the latest subdirectory 
 # gets replaced with the generated documentation from the new version 
 latest_subdirectory_name="latest"
@@ -93,18 +73,24 @@ $(xcrun --find docc) process-archive transform-for-static-hosting "${source_arch
     --output-path "${output_path}" \
     --hosting-base-path "${hosting_base_path}"
 
-# Replace index.html with a redirect to documentation/muxspaces/
-sed -e "s/__VERSION__/${sdk_semantic_version}/" "${TOP_DIR}/scripts/index.html.template" > ${output_path}/index.html
+# Replace index.html with a redirect to documentation/your-lib-name/ for your version
+sed -e "s/__VERSION__/${sdk_semantic_version}/g" \
+    -e "s/__SLUG__/${DOCS_ROOT_DIR}/g" \
+    "scripts/docc-files/index.html.template" > ${output_path}/index.html
 
 mkdir -p $DOCS_ROOT_DIR
 
 mkdir -p $DOCS_ROOT_DIR/$latest_subdirectory_name
 
-# Replace index.html with a redirect to documentation/muxspaces/
-sed -e "s/__VERSION__/${latest_subdirectory_name}/" "${TOP_DIR}/scripts/index.html.template" > $DOCS_ROOT_DIR/${latest_subdirectory_name}/index.html
+# Replace index.html with a redirect to documentation/your-lib-name/ for 'latest'
+sed -e "s/__VERSION__/${latest_subdirectory_name}/" \
+    -e "s/__SLUG__/${DOCS_ROOT_DIR}/g" \
+    "scripts/docc-files/index.html.template" > $DOCS_ROOT_DIR/${latest_subdirectory_name}/index.html
 
+# For the record this overwrites our faked index.html but that helps it work
 cp -r ./$output_path/. ./$DOCS_ROOT_DIR/$latest_subdirectory_name
 
+
 mv $output_path $DOCS_ROOT_DIR
 
 zip -qry "${DOCS_ROOT_DIR}.zip" "${DOCS_ROOT_DIR}"

README.md

@@ -0,0 +1,6 @@
+<!DOCTYPE html>
+<meta charset="utf-8">
+<!-- This file is intended to replace the automatically generated index.html so it redirects to the "real" homepage for __SLUG__ docs -->
+<title>Redirecting to __SLUG__ homepage</title>
+<meta http-equiv="refresh" content="0; URL=/__SLUG__/documentation/__TARGET__/">
+<link rel="canonical" href="/__SLUG__/documentation/__TARGET__/"/>

scripts/create-docc-archive.sh

@@ -0,0 +1 @@
+{}

scripts/docc-files/index.html.template

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+if [ -z $1 ]
+then
+    echo -e "\033[1;31m ERROR: this script requires a repository name parameter. \033[0m"
+    exit $E_MISSING_POS_PARAM
+fi
+
+if [ -z $2 ]
+then
+    echo -e "\033[1;31m ERROR: this script requires a target name parameter. \033[0m"
+    exit $E_MISSING_POS_PARAM
+fi
+
+echo "▸ Adding redirect from the docc static archive root"
+
+output_path="docs"
+
+sed -e "s/__SLUG__/${1}/g" \
+    -e "s/__TARGET__/${2}/g" \
+    "scripts/docc-files/index.html.template" > ${output_path}/index.html
+
+echo "▸ Rewrote ${output_path}/index.html to:"
+
+cat ${output_path}/index.html
+
+echo "▸ Copy theme settings to static archive"
+
+cp scripts/docc-files/theme-settings.json docs