swift: generate API docs as a DocC archive

.github/workflows/release.yml

@@ -132,6 +132,22 @@ jobs:
         with:
           name: ios_framework
           path: ./Envoy.xcframework.zip
+      - name: 'Build Envoy.doccarchive.zip'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          ./bazelw build \
+            --output_groups=+swift_symbol_graph \
+            --config=release-ios \
+            --config=remote-ci-macos \
+            --remote_header="Authorization=Bearer $GITHUB_TOKEN" \
+            //library/swift:ios_lib
+          ./tools/docc.sh bazel-bin/library/swift/ios_lib.symbolgraph
+          zip -r Envoy.doccarchive.zip Envoy.doccarchive
+      - uses: actions/upload-artifact@v2
+        with:
+          name: ios_docs
+          path: ./Envoy.doccarchive.zip
 
   create_github_release:
     name: create_github_release
@@ -146,10 +162,14 @@ jobs:
       - uses: actions/download-artifact@v3
         with:
           name: ios_framework
+      - uses: actions/download-artifact@v3
+        with:
+          name: ios_docs
       - name: Release
         uses: softprops/action-gh-release@v1
         with:
           prerelease: true
           files: |
             envoy_android_aar_sources.tar.gz
             Envoy.xcframework.zip
+            Envoy.doccarchive.zip

.gitignore

@@ -12,6 +12,7 @@
 *.pyc
 *.tulsiconf-user
 *.xcodeproj
+Envoy.doccarchive/
 clang.bazelrc
 user.bazelrc
 tags

bazel/envoy_mobile_repositories.bzl

@@ -78,12 +78,12 @@ def swift_repos():
         url = "https://github.com/bazelbuild/rules_apple/archive/29f5b63d702f1d071f95343be29d4c23045e0e84.tar.gz",
     )
 
-    # TODO(jpsim): Update to the next release which includes https://github.com/bazelbuild/rules_swift/pull/818
+    # https://github.com/bazelbuild/rules_swift/pull/838
     http_archive(
         name = "build_bazel_rules_swift",
-        sha256 = "b5966b422113866398035cd970feffb4ab6c081fa1c96c02d942b17e5b8429c4",
-        strip_prefix = "rules_swift-8d4b096b90e47095755e47c27e749ae9b9f83e81",
-        url = "https://github.com/bazelbuild/rules_swift/archive/8d4b096b90e47095755e47c27e749ae9b9f83e81.tar.gz",
+        sha256 = "a3fac55d12f33a2d030b816e189eaa84218fd0fc501fc93ded0b1dcba01e47fb",
+        strip_prefix = "rules_swift-3bc7bc164020a842ae08e0cf071ed35f0939dd39",
+        url = "https://github.com/bazelbuild/rules_swift/archive/3bc7bc164020a842ae08e0cf071ed35f0939dd39.tar.gz",
     )
 
     http_archive(

docs/root/intro/version_history.rst

@@ -30,6 +30,7 @@ Features:
 - android: enable the filtering of unroutable families by default. (:issues: `#2267 <2267>`)
 - instrumentation: add timers and warnings to platform-provided callbacks (:issue: `#2300 <2300>`)
 - iOS: add support for integrating Envoy Mobile via the Swift Package Manager
+- iOS: A documentation archive is now included in the GitHub release artifact (:issue: `#2335 <2335>`)
 
 0.4.6 (April 26, 2022)
 ========================

library/swift/BUILD

@@ -46,7 +46,10 @@ swift_library(
         "mocks/*.swift",
         "stats/*.swift",
     ]) + ["@envoy_mobile_extra_swift_sources//:extra_swift_srcs"],
-    features = ["swift.enable_library_evolution"],
+    features = [
+        "swift.emit_symbol_graph",
+        "swift.enable_library_evolution",
+    ],
     generates_header = True,
     module_name = "Envoy",
     private_deps = [

tools/docc.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+symbolgraph_dir="${1:-}"
+if [[ -z "$symbolgraph_dir" ]]; then
+  ./bazelw build //library/swift:ios_lib --config=release-ios --output_groups=+swift_symbol_graph
+  symbolgraph_dir="bazel-bin/library/swift/ios_lib.symbolgraph"
+fi
+
+"$(xcrun --find docc)" convert \
+  --index \
+  --fallback-display-name Envoy \
+  --fallback-bundle-identifier io.envoyproxy.EnvoyMobile \
+  --fallback-bundle-version "$(cat VERSION)" \
+  --output-dir Envoy.doccarchive \
+  --additional-symbol-graph-dir "$symbolgraph_dir"