From eac8374320f7b8c4be9c184ed4e460ef55743134 Mon Sep 17 00:00:00 2001 From: JP Simard Date: Thu, 2 Jun 2022 09:40:58 -0400 Subject: [PATCH 1/2] swift: generate API docs as a DocC archive And include in GitHub release artifacts Updates rules_swift to pull in https://github.com/bazelbuild/rules_swift/pull/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. Signed-off-by: JP Simard --- .github/workflows/release.yml | 19 +++++++++++++++++++ .gitignore | 1 + bazel/envoy_mobile_repositories.bzl | 8 ++++---- docs/root/intro/version_history.rst | 1 + library/swift/BUILD | 5 ++++- tools/docc.sh | 17 +++++++++++++++++ 6 files changed, 46 insertions(+), 5 deletions(-) create mode 100755 tools/docc.sh diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4239544c8d..b48f0d31da 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -132,6 +132,21 @@ jobs: with: name: ios_framework path: ./Envoy.xcframework.zip + - name: 'Build Envoy.doccarchive' + 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 + - uses: actions/upload-artifact@v2 + with: + name: ios_docs + path: ./Envoy.doccarchive create_github_release: name: create_github_release @@ -146,6 +161,9 @@ 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: @@ -153,3 +171,4 @@ jobs: files: | envoy_android_aar_sources.tar.gz Envoy.xcframework.zip + Envoy.doccarchive diff --git a/.gitignore b/.gitignore index e52f81155e..fbadef3707 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,7 @@ *.pyc *.tulsiconf-user *.xcodeproj +Envoy.doccarchive/ clang.bazelrc user.bazelrc tags diff --git a/bazel/envoy_mobile_repositories.bzl b/bazel/envoy_mobile_repositories.bzl index 98b29edd88..d3563c1f8d 100644 --- a/bazel/envoy_mobile_repositories.bzl +++ b/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( diff --git a/docs/root/intro/version_history.rst b/docs/root/intro/version_history.rst index cf2ca448a0..fd1247bb5d 100644 --- a/docs/root/intro/version_history.rst +++ b/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) ======================== diff --git a/library/swift/BUILD b/library/swift/BUILD index 680c443fef..4895734390 100644 --- a/library/swift/BUILD +++ b/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 = [ diff --git a/tools/docc.sh b/tools/docc.sh new file mode 100755 index 0000000000..d64a7961c0 --- /dev/null +++ b/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" From f72e0011ae40b3e21ab3e8ac7e7e62e28185b535 Mon Sep 17 00:00:00 2001 From: JP Simard Date: Thu, 2 Jun 2022 11:41:37 -0400 Subject: [PATCH 2/2] zip Signed-off-by: JP Simard --- .github/workflows/release.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b48f0d31da..8199b4beda 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -132,7 +132,7 @@ jobs: with: name: ios_framework path: ./Envoy.xcframework.zip - - name: 'Build Envoy.doccarchive' + - name: 'Build Envoy.doccarchive.zip' env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | @@ -143,10 +143,11 @@ jobs: --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 + path: ./Envoy.doccarchive.zip create_github_release: name: create_github_release @@ -171,4 +172,4 @@ jobs: files: | envoy_android_aar_sources.tar.gz Envoy.xcframework.zip - Envoy.doccarchive + Envoy.doccarchive.zip