add script to generate docs and files for static websites

mozilla · Aug 26, 2024 · 7648dad · 7648dad
1 parent 3689890
commit 7648dad
Show file tree

Hide file tree

Showing 12 changed files with 905 additions and 0 deletions.
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
@@ -0,0 +1,114 @@
+name: Generate and Deploy Documentation
+
+on:
+  push:
+    branches:
+      - generate-docs # replace with main
+
+jobs:
+  build-docs:
+    runs-on: macos-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0  # Ensures all branches are fetched
+
+      - name: Select Xcode Command Line Tools 15.1
+        run: |
+          sudo xcode-select -s /Applications/Xcode_15.1.app/Contents/Developer
+
+      - name: Install Homebrew
+        run: |
+          /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+        shell: bash
+
+      - name: Clone application-services repository with submodules
+        run: |
+          git clone https://github.com/mozilla/application-services.git /tmp/application-services
+          cd /tmp/application-services
+          git submodule init
+          git submodule update --recursive
+
+      - name: Install Python, setuptools, six and gyp
+        run: |
+          brew install ninja python@3.9 python-setuptools
+          
+          # Create and activate a virtual environment
+          python3.9 -m venv myenv
+          source myenv/bin/activate
+          
+          # Upgrade pip and install setuptools and six within the virtual environment
+          pip install --upgrade pip setuptools six
+          
+          
+          wget https://bootstrap.pypa.io/ez_setup.py -O - | python3 -
+          git clone https://chromium.googlesource.com/external/gyp.git ~/tools/gyp
+          cd ~/tools/gyp
+          python3.9 setup.py install
+          
+          echo "export PATH=~/tools/gyp:\$PATH" >> ~/.bash_profile
+          echo 'export PATH="$PATH:$(brew --prefix)/opt/python@3.9/Frameworks/Python.framework/Versions/3.9/bin"' >> ~/.bash_profile
+        shell: bash
+
+      - name: Setup iOS environment
+        run: |
+          # Activate the virtual environment
+          source myenv/bin/activate  
+          
+          # Copy over the build files without iOS-simulator and x86 targets
+          cp ./automation/build-docs/overwrites/build-all-ios.sh /tmp/application-services/libs/
+          cp ./automation/build-docs/overwrites/build-nss-ios.sh /tmp/application-services/libs/
+          cp ./automation/build-docs/overwrites/verify-ios-ci-environment.sh /tmp/application-services/libs/   
+          
+          # Overwrite how to build the swift code (without FirefoxFocus and x86 targets)
+          cp ./automation/build-docs/overwrites/build-and-test-swift.py /tmp/application-services/taskcluster/scripts/
+    
+          cp ./automation/build-docs/overwrites/build-xcframework.sh /tmp/application-services/megazords/ios-rust/
+          cd /tmp/application-services
+          ./libs/verify-ios-ci-environment.sh
+        shell: bash
+
+      - name: Build the XCFramework from application-services
+        run: |
+          cd ./automation/build-docs/
+          ./build_local_xcframework_for_docs.sh /tmp/application-services
+
+      - name: Build the documentation
+        run: |
+          cd ./automation/build-docs/
+          ./generate_docs.sh
+
+      - name: Upload Documentation as Artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: ./automation/build-docs/docs-website
+
+  deploy-docs:
+    runs-on: ubuntu-latest
+    needs: build-docs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0  # Ensures all branches are fetched
+
+      - name: Download Documentation
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+          path: ./automation/build-docs/docs-website
+
+      - name: Deploy to /docs Branch
+        run: |
+          git checkout --orphan docs
+          git reset --hard
+          cp -r ./automation/build-docs/docs-website* .
+          git add -A
+          git commit -m "Deploy documentation to /docs branch"
+          git push -f origin docs
+
+      - name: Clean up workspace
+        run: |
+          git checkout main
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,12 @@ Package.resolved
 
 # From the Glean sdk generator
 .venv
+
+# Docs generation
+/automation/build-docs/docs-website/
+/automation/build-docs/docs_output/
+/automation/build-docs/MozillaRustComponents.xcframework
+/automation/build-docs/build
+automation/build-docs/swift-source/
+
+.idea
diff --git a/automation/build-docs/MozillaRustComponentsWrapper/dummy.m b/automation/build-docs/MozillaRustComponentsWrapper/dummy.m
@@ -0,0 +1,6 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+// Swift Package Manager needs at least one source file.
diff --git a/automation/build-docs/MozillaRustComponentsWrapper/include/dummy.h b/automation/build-docs/MozillaRustComponentsWrapper/include/dummy.h
@@ -0,0 +1,7 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+// Swift Package Manager needs at least one header to prevent a warning. See
+// https://github.com/mozilla/application-services/issues/4422.
diff --git a/automation/build-docs/Package.swift b/automation/build-docs/Package.swift
@@ -0,0 +1,50 @@
+// swift-tools-version:5.5
+import PackageDescription
+
+let checksum = "0830da14106bd3068c8beb68cf6b4a5e0ce6251d40f31446c812ab18dc244de0"
+let version = "131.0.20240821050323"
+let url = "https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/project.application-services.v2.swift.131.20240821050323/artifacts/public/build/MozillaRustComponents.xcframework.zip"
+
+let package = Package(
+    name: "MozillaRustComponentsSwift",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(name: "MozillaAppServices", targets: ["MozillaAppServices"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/mozilla/glean-swift", from: "61.0.0")
+    ],
+    targets: [
+        /*
+        * A placeholder wrapper for our binaryTarget so that Xcode will ensure this is
+        * downloaded/built before trying to use it in the build process
+        * A bit hacky but necessary for now https://github.com/mozilla/application-services/issues/4422
+        */
+        .target(
+            name: "MozillaRustComponentsWrapper",
+            dependencies: [
+                .target(name: "MozillaRustComponents", condition: .when(platforms: [.iOS])),
+                .product(name: "Glean", package: "glean-swift")
+            ],
+            path: "MozillaRustComponentsWrapper"
+        ),
+        .binaryTarget(
+            name: "MozillaRustComponents",
+            //
+            // For release artifacts, reference the MozillaRustComponents as a URL with checksum.
+            // IMPORTANT: The checksum has to be on the line directly after the `url`
+            // this is important for our release script so that all values are updated correctly
+            path: "./MozillaRustComponents.xcframework"
+
+            // For local testing, you can point at an (unzipped) XCFramework that's part of the repo.
+            // Note that you have to actually check it in and make a tag for it to work correctly.
+            //
+            //path: "./MozillaRustComponents.xcframework"
+        ),
+        .target(
+            name: "MozillaAppServices",
+            dependencies: ["MozillaRustComponentsWrapper"],
+            path: "swift-source/all"
+        ),
+    ]
+)
diff --git a/automation/build-docs/build_local_xcframework_for_docs.sh b/automation/build-docs/build_local_xcframework_for_docs.sh
@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+# Uses a local version of application services xcframework
+
+# This script allows switches the usage of application services to a local xcframework
+# built from a local checkout of application services
+
+set -e
+
+# CMDNAME is used in the usage text below
+CMDNAME=$(basename "$0")
+USAGE=$(cat <<EOT
+${CMDNAME}
+Tarik Eshaq <teshaq@mozilla.com>
+
+Uses a local version of application services xcframework
+
+This script allows switches the usage of application services to a local xcframework
+built from a local checkout of application services
+
+
+USAGE:
+    ${CMDNAME} [OPTIONS] <LOCAL_APP_SERVICES_PATH>
+
+OPTIONS:
+    -d, --disable           Disables local development on application services
+    -h, --help              Display this help message.
+EOT
+)
+
+msg () {
+  printf "\033[0;34m> %s\033[0m\n" "${1}"
+}
+
+helptext() {
+    echo "$USAGE"
+}
+
+
+
+THIS_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+PACKAGE_FILE="$THIS_DIR/Package.swift"
+SWIFT_SOURCE="$THIS_DIR/swift-source"
+FRAMEWORK_PATH="./MozillaRustComponents.xcframework"
+FRAMEWORK_PATH_ESCAPED=$( echo $FRAMEWORK_PATH |  sed 's/\//\\\//g' )
+APP_SERVICES_REMOTE="https://github.com/mozilla/application-services"
+
+DISABLE="false"
+APP_SERVICES_DIR=
+while (( "$#" )); do
+    case "$1" in
+        -d|--disable)
+            DISABLE="true"
+            shift
+            ;;
+        -h|--help)
+            helptext
+            exit 0
+            ;;
+        --) # end argument parsing
+            shift
+            break
+            ;;
+        --*=|-*) # unsupported flags
+            echo "Error: Unsupported flag $1" >&2
+            exit 1
+            ;;
+        *) # preserve positional arguments
+            APP_SERVICES_DIR=$1
+            shift
+            ;;
+    esac
+done
+
+if [ "true" = $DISABLE ]; then
+  msg "Resetting $PACKAGE_FILE to use remote xcframework"
+  # We disable the local development and revert back
+  # ideally, users should just use git reset.
+  #
+  # This exist so local development can be easy to enable/disable
+  # and we trust that once developers are ready to push changes
+  # they will clean the files to make sure they are in the same
+  # state they were in before any of the changes happened.
+  perl -0777 -pi -e "s/            path: \"$FRAMEWORK_PATH_ESCAPED\"/            url: url,
+            checksum: checksum/igs" $PACKAGE_FILE
+
+  msg "Done reseting $PACKAGE_FILE"
+  git add $PACKAGE_FILE
+  msg "$PACKAGE_FILE changes staged"
+
+  if [ -d $FRAMEWORK_PATH ]; then
+    msg "Detected local framework, deleting it.."
+    rm -rf $FRAMEWORK_PATH
+    git add $FRAMEWORK_PATH
+    msg "Deleted and staged the deletion of the local framework"
+  fi
+  msg "IMPORTANT: reminder that changes to this repository are not visable to consumers until
+      commited"
+  exit 0
+fi
+
+if [ -z $APP_SERVICES_DIR ]; then
+    msg "Please set the application-services path."
+    msg "This is a path to a local checkout of the application services repository"
+    msg "You can find the repository on $APP_SERVICES_REMOTE"
+    exit 1
+fi
+
+## We replace the url and checksum in the Package.swift with a refernce to the local
+## framework path
+perl -0777 -pi -e "s/            url: url,
+            checksum: checksum/            path: \"$FRAMEWORK_PATH_ESCAPED\"/igs" $PACKAGE_FILE
+
+
+## First we build the xcframework in the application services repository
+msg "Building the xcframework in $APP_SERVICES_DIR"
+msg "This might take a few minutes"
+pushd $APP_SERVICES_DIR
+./taskcluster/scripts/build-and-test-swift.py "$SWIFT_SOURCE" "$THIS_DIR" "$THIS_DIR/build/glean-dir" --force_build
+popd
+unzip -o "$THIS_DIR/MozillaRustComponents.xcframework.zip" && rm "$THIS_DIR/MozillaRustComponents.xcframework.zip"
+
+rm -rf FocusRustComponents.xcframework.zip
diff --git a/automation/build-docs/generate_docs.sh b/automation/build-docs/generate_docs.sh
@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# Define variables
+OUTPUT_DIR="./docs_output"
+
+SCHEME="MozillaRustComponentsSwift"
+DESTINATION="generic/platform=iOS"
+DOCC_NAME="MozillaAppServices"
+DOCC_ARCHIVE_PATH="$OUTPUT_DIR/Build/Products/Debug-iphoneos/$DOCC_NAME.doccarchive"
+STATIC_FILES_FOLDER="./docs-website"
+
+# Run xcodebuild to build documentation
+echo "Running xcodebuild for documentation generation..."
+xcodebuild docbuild -scheme $SCHEME -destination $DESTINATION -derivedDataPath $OUTPUT_DIR
+
+# Run xcrun to generate the final DocC archive
+echo "Running xcrun to generate DocC archive..."
+xcrun docc process-archive transform-for-static-hosting $DOCC_ARCHIVE_PATH --output-path $STATIC_FILES_FOLDER --hosting-base-path DOCC_NAME
+
+# Cleanup
+echo "Cleaning up..."
+rm -rf "swift-source"
+rm -rf "MozillaRustComponents.xcframework"
+
+echo "Documentation generation completed. Output available in $STATIC_FILES_FOLDER"