Jazzy docs generation workflow

.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Docs Generation
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: macos-latest
+
+    permissions:
+      deployments: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Select Specific Xcode Version
+        run: |
+          sudo xcode-select -s /Applications/Xcode_13.2.app
+          echo "Selected Xcode version:"
+          xcodebuild -version
+
+      - name: Install Dependencies
+        run: |
+          make submodules
+          bundle install
+          make update_carthage_dependencies_macos
+
+      - name: Build Documentation
+        run: |
+          ./Scripts/jazzy.sh
+          ls -al Docs/jazzy
+
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        with:
+          aws-region: eu-west-2
+          role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-cocoa
+          role-session-name: "${{ github.run_id }}-${{ github.run_number }}"
+
+      - name: Upload Documentation
+        uses: ably/sdk-upload-action@v1
+        with:
+          sourcePath: Docs/jazzy
+          githubToken: ${{ secrets.GITHUB_TOKEN }}
+          artifactName: jazzydoc
+

.gitignore

@@ -71,3 +71,7 @@ Examples/Tests/Podfile.lock
 # AppCode
 .build
 .idea
+
+# Jazzy Docs
+Docs/jazzy
+

Gemfile

@@ -4,6 +4,8 @@
 
 source "https://rubygems.org"
 
+gem 'jazzy'
+
 gem 'fastlane'
 
 plugins_path = File.join(File.dirname(__FILE__), 'fastlane', 'Pluginfile')

Gemfile.lock

@@ -3,8 +3,17 @@ GEM
   specs:
     CFPropertyList (3.0.5)
       rexml
+    activesupport (6.1.6)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
     addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
+    algoliasearch (1.27.5)
+      httpclient (~> 2.8, >= 2.8.3)
+      json (>= 1.5.1)
     artifactory (3.0.15)
     atomos (0.1.3)
     aws-eventstream (1.2.0)
@@ -25,17 +34,58 @@ GEM
       aws-eventstream (~> 1, >= 1.0.2)
     babosa (1.0.4)
     claide (1.1.0)
+    cocoapods (1.11.3)
+      addressable (~> 2.8)
+      claide (>= 1.0.2, < 2.0)
+      cocoapods-core (= 1.11.3)
+      cocoapods-deintegrate (>= 1.0.3, < 2.0)
+      cocoapods-downloader (>= 1.4.0, < 2.0)
+      cocoapods-plugins (>= 1.0.0, < 2.0)
+      cocoapods-search (>= 1.0.0, < 2.0)
+      cocoapods-trunk (>= 1.4.0, < 2.0)
+      cocoapods-try (>= 1.1.0, < 2.0)
+      colored2 (~> 3.1)
+      escape (~> 0.0.4)
+      fourflusher (>= 2.3.0, < 3.0)
+      gh_inspector (~> 1.0)
+      molinillo (~> 0.8.0)
+      nap (~> 1.0)
+      ruby-macho (>= 1.0, < 3.0)
+      xcodeproj (>= 1.21.0, < 2.0)
+    cocoapods-core (1.11.3)
+      activesupport (>= 5.0, < 7)
+      addressable (~> 2.8)
+      algoliasearch (~> 1.0)
+      concurrent-ruby (~> 1.1)
+      fuzzy_match (~> 2.0.4)
+      nap (~> 1.0)
+      netrc (~> 0.11)
+      public_suffix (~> 4.0)
+      typhoeus (~> 1.0)
+    cocoapods-deintegrate (1.0.5)
+    cocoapods-downloader (1.6.3)
+    cocoapods-plugins (1.0.0)
+      nap
+    cocoapods-search (1.0.1)
+    cocoapods-trunk (1.6.0)
+      nap (>= 0.8, < 2.0)
+      netrc (~> 0.11)
+    cocoapods-try (1.2.0)
     colored (1.2)
     colored2 (3.1.2)
     commander (4.6.0)
       highline (~> 2.0.0)
+    concurrent-ruby (1.1.10)
     declarative (0.0.20)
     digest-crc (0.6.4)
       rake (>= 12.0.0, < 14.0.0)
     domain_name (0.5.20190701)
       unf (>= 0.0.5, < 1.0.0)
     dotenv (2.7.6)
     emoji_regex (3.2.3)
+    escape (0.0.4)
+    ethon (0.15.0)
+      ffi (>= 1.15.0)
     excon (0.91.0)
     faraday (1.10.0)
       faraday-em_http (~> 1.0)
@@ -105,6 +155,9 @@ GEM
       xcodeproj (>= 1.13.0, < 2.0.0)
       xcpretty (~> 0.3.0)
       xcpretty-travis-formatter (>= 0.0.3)
+    ffi (1.15.5)
+    fourflusher (2.3.1)
+    fuzzy_match (2.0.4)
     gh_inspector (1.1.3)
     google-apis-androidpublisher_v3 (0.16.0)
       google-apis-core (>= 0.4, < 2.a)
@@ -148,30 +201,53 @@ GEM
     http-cookie (1.0.4)
       domain_name (~> 0.5)
     httpclient (2.8.3)
+    i18n (1.10.0)
+      concurrent-ruby (~> 1.0)
+    jazzy (0.14.2)
+      cocoapods (~> 1.5)
+      mustache (~> 1.1)
+      open4 (~> 1.3)
+      redcarpet (~> 3.4)
+      rexml (~> 3.2)
+      rouge (>= 2.0.6, < 4.0)
+      sassc (~> 2.1)
+      sqlite3 (~> 1.3)
+      xcinvoke (~> 0.3.0)
     jmespath (1.6.0)
     json (2.6.1)
     jwt (2.3.0)
+    liferaft (0.0.6)
     memoist (0.16.2)
     mini_magick (4.11.0)
     mini_mime (1.1.2)
+    minitest (5.15.0)
+    molinillo (0.8.0)
     multi_json (1.15.0)
     multipart-post (2.0.0)
+    mustache (1.1.1)
     nanaimo (0.3.0)
+    nap (1.1.0)
     naturally (2.2.1)
+    netrc (0.11.0)
+    open4 (1.3.4)
     optparse (0.1.1)
     os (1.1.4)
     plist (3.6.0)
     public_suffix (4.0.6)
     rake (13.0.6)
+    redcarpet (3.5.1)
     representable (3.1.1)
       declarative (< 0.1.0)
       trailblazer-option (>= 0.1.1, < 0.2.0)
       uber (< 0.2.0)
     retriable (3.1.2)
     rexml (3.2.5)
     rouge (2.0.7)
+    ruby-macho (2.5.1)
     ruby2_keywords (0.0.5)
     rubyzip (2.3.2)
+    sassc (2.4.0)
+      ffi (~> 1.9)
     security (0.1.3)
     signet (0.16.0)
       addressable (~> 2.8)
@@ -181,6 +257,7 @@ GEM
     simctl (1.6.8)
       CFPropertyList
       naturally
+    sqlite3 (1.4.2)
     terminal-notifier (2.0.0)
     terminal-table (1.8.0)
       unicode-display_width (~> 1.1, >= 1.1.1)
@@ -189,13 +266,19 @@ GEM
     tty-screen (0.8.1)
     tty-spinner (0.9.3)
       tty-cursor (~> 0.7)
+    typhoeus (1.4.0)
+      ethon (>= 0.9.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
     uber (0.1.0)
     unf (0.1.4)
       unf_ext
     unf_ext (0.0.8)
     unicode-display_width (1.8.0)
     webrick (1.7.0)
     word_wrap (1.0.0)
+    xcinvoke (0.3.0)
+      liferaft (~> 0.0.6)
     xcodeproj (1.21.0)
       CFPropertyList (>= 2.3.3, < 4.0)
       atomos (~> 0.1.3)
@@ -207,12 +290,14 @@ GEM
       rouge (~> 2.0.7)
     xcpretty-travis-formatter (1.0.1)
       xcpretty (~> 0.2, >= 0.0.7)
+    zeitwerk (2.5.4)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   fastlane
+  jazzy
 
 BUNDLED WITH
-   2.3.6
+   2.3.15

Scripts/jazzy.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# Generates Jazzy documentation: https://github.com/realm/jazzy
+# This script performs without issues on CI. To generate docs locally see https://github.com/ably/ably-cocoa/issues/1438
+
+jazzy \
+  --objc \
+  --clean \
+  --author Ably \
+  --module-version 1.2.10 \
+  --umbrella-header Source/Ably.h \
+  --framework-root . \
+  --module Ably \
+  --sdk iphonesimulator \
+  --output Docs/jazzy

Scripts/set-version.sh

@@ -27,9 +27,10 @@ echo "$VERSION_CONFIG_VAR = $NEW_VERSION" > $VERSION_CONFIG_FILE
 
 sed -i '' -e 's/'"$OLD_VERSION"'/'"$NEW_VERSION"'/g' README.md
 sed -i '' -e 's/'"$OLD_VERSION"'/'"$NEW_VERSION"'/g' Spec/Tests/RealtimeClientConnectionTests.swift
+sed -i '' -e 's/'"$OLD_VERSION"'/'"$NEW_VERSION"'/g' Scripts/jazzy.sh
 
 git add README.md
 git add Spec/Tests/RealtimeClientConnectionTests.swift
 git add Version.xcconfig
+git add Scripts/jazzy.sh
 git commit -m "Bump version to $NEW_VERSION."
-

Source/Ably.h

@@ -47,9 +47,6 @@ FOUNDATION_EXPORT const unsigned char ablyVersionString[];
 #import <Ably/ARTPush.h>
 #import <Ably/ARTPushChannel.h>
 #import <Ably/ARTPushChannelSubscription.h>
-#import <Ably/ARTPushActivationStateMachine.h>
-#import <Ably/ARTPushActivationEvent.h>
-#import <Ably/ARTPushActivationState.h>
 #import <Ably/ARTPushAdmin.h>
 #import <Ably/ARTPushChannelSubscriptions.h>
 #import <Ably/ARTPushDeviceRegistrations.h>

Source/Ably.modulemap

@@ -46,6 +46,9 @@ framework module Ably {
         header "ARTPushAdmin+Private.h"
         header "ARTPushDeviceRegistrations+Private.h"
         header "ARTPushChannelSubscriptions+Private.h"
+        header "ARTPushActivationState.h"
+        header "ARTPushActivationEvent.h"
+        header "ARTPushActivationStateMachine.h"
         header "ARTPushActivationStateMachine+Private.h"
         header "ARTPushChannel+Private.h"
         header "ARTNSMutableRequest+ARTPush.h"

Source/PrivateHeaders/Ably/ARTPushActivationEvent.h

@@ -0,0 +1 @@
+../../../Source/ARTPushActivationEvent.h

Source/PrivateHeaders/Ably/ARTPushActivationState.h

@@ -0,0 +1 @@
+../../../Source/ARTPushActivationState.h

Source/PrivateHeaders/Ably/ARTPushActivationStateMachine.h

@@ -0,0 +1 @@
+../../../Source/ARTPushActivationStateMachine.h

Source/include/Ably.modulemap

@@ -40,11 +40,15 @@ framework module Ably {
         header "Ably/ARTRealtimePresence+Private.h"
         header "Ably/ARTRestPresence+Private.h"
         header "Ably/ARTFallback+Private.h"
+        header "Ably/ARTFallbackHosts.h"
         header "Ably/ARTLocalDevice+Private.h"
         header "Ably/ARTPush+Private.h"
         header "Ably/ARTPushAdmin+Private.h"
         header "Ably/ARTPushDeviceRegistrations+Private.h"
         header "Ably/ARTPushChannelSubscriptions+Private.h"
+        header "Ably/ARTPushActivationState.h"
+        header "Ably/ARTPushActivationEvent.h"
+        header "Ably/ARTPushActivationStateMachine.h"
         header "Ably/ARTPushActivationStateMachine+Private.h"
         header "Ably/ARTPushChannel+Private.h"
         header "Ably/ARTNSMutableRequest+ARTPush.h"
@@ -59,8 +63,17 @@ framework module Ably {
         header "Ably/ARTJsonEncoder.h"
         header "Ably/ARTMsgPackEncoder.h"
         header "Ably/ARTFormEncode.h"
-        header "Ably/ARTSRWebSocket.h"
         header "Ably/ARTStringifiable+Private.h"
+        header "Ably/ARTSRWebSocket.h"
+        header "Ably/ARTGCD.h"
+        header "Ably/ARTNSArray+ARTFunctional.h"
+        header "Ably/ARTNSDictionary+ARTDictionaryUtil.h"
+        header "Ably/ARTNSString+ARTUtil.h"
+        header "Ably/ARTOSReachability.h"
+        header "Ably/NSURLRequest+ARTSRWebSocket.h"
+        header "Ably/NSRunLoop+ARTSRWebSocket.h"
+        header "Ably/ARTSRSecurityPolicy.h"
+        header "Ably/ARTStringifiable.h"
         header "Ably/ARTNSMutableDictionary+ARTDictionaryUtil.h"
         header "Ably/NSURLQueryItem+Stringifiable.h"
         header "Ably/ARTNSError+ARTUtils.h"