swift: generate API docs as a DocC archive (#2335)

And include in GitHub release artifacts

Updates rules_swift to pull in
bazelbuild/rules_swift#838

When users open the archive, they'll have rich docs they can explore
using Xcode's documentation navigator.

When we update to Xcode 13.4, we'll be able to generate HTML docs with
this approach and publish to the documentation website. Here's a demo of
what that static site looks like:
https://envoy-mobile-docc-demo.netlify.app/documentation/envoy/

https://user-images.githubusercontent.com/474794/171704142-993072a3-fbc2-4db6-9c70-65e9e1a47aac.mp4

Risk Level: Low
Testing: Local, CI
Docs Changes: Added
Release Notes: Added

Signed-off-by: JP Simard <jp@jpsim.com>

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