Merge pull request #8 from AgoraIO/add-docc

Added DocC
AgoraIO · Jul 3, 2023 · 8e6f230 · 8e6f230
2 parents 07aeab0 + cfc10c3
commit 8e6f230
Show file tree

Hide file tree

Showing 6 changed files with 340 additions and 1 deletion.
diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml
@@ -0,0 +1,123 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy DocC
+
+on:
+  # Runs on new releases
+  release:
+    types: [published]
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+env:
+  PACKAGE_NAME: AgoraRtcKit
+  BUILD_DEST: generic/platform=iOS
+  BUILD_PRODUCT: Debug-iphoneos
+  JSON_TEMPLATE_BASE: https://github.com/AgoraIO/agora_doc_source/releases/download/master-build/ios_ng_json_template
+
+jobs:
+  generate-docc:
+    name: Build DocC Archives
+    runs-on: macos-13
+    strategy:
+      matrix:
+        language: ['en', 'cn']
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+      - name: Switch Xcode 🔄
+        run: sudo xcode-select --switch /Applications/Xcode_14.3.app
+      - name: Clone DocC Helper 👭
+        uses: actions/checkout@v3
+        with:
+          repository: maxxfrazer/xcframework-to-docc
+          path: xcframework-to-docc
+      - name: Setup Xcode Project 🛠️
+        run: |
+          sh -e xcframework-to-docc/dl_framework.sh ${{ env.PACKAGE_NAME }}
+          sh -e xcframework-to-docc/move_header_files.sh ${{ env.PACKAGE_NAME }}.xcframework ${{ env.PACKAGE_NAME }}.docc
+          sh -e xcframework-to-docc/headers_to_xcodeproj.sh ${{ env.PACKAGE_NAME }} docc_builder
+      - name: Clone Python Script 👭
+        uses: actions/checkout@v3
+        with:
+          repository: littleGnAl/iris-doc
+          path: iris-doc
+      - name: Set up python 3.9 🐍
+        uses: actions/setup-python@v4
+        with:
+            python-version: '3.9'
+      - name: Add Inline Docs (${{ matrix.language }}) 📕
+        run: |
+          cd iris-doc
+          python -m pip install -r requirements.txt
+          python iris_doc.py \
+            --config=$(pwd)/fmt_config/fmt_oc.yaml \
+            --language=oc \
+            --template-url=${{ env.JSON_TEMPLATE_BASE }}_${{ matrix.language }}.json \
+            --export-file-path=$(pwd)/../docc_builder/${{ env.PACKAGE_NAME }}/Headers/${{ env.PACKAGE_NAME }}.h
+      - name: Generate DocC Archive (${{ matrix.language }}) 🪄
+        run: xcodebuild -project docc_builder/${{ env.PACKAGE_NAME }}.xcodeproj docbuild -scheme ${{ env.PACKAGE_NAME }} -derivedDataPath /tmp/docbuild -destination ${{ env.BUILD_DEST }}
+      - name: Zip It Up (${{ matrix.language }}) 🤐
+        run: |
+          mv /tmp/docbuild/Build/Products/${{ env.BUILD_PRODUCT }}/${{ env.PACKAGE_NAME }}.doccarchive ${{ env.PACKAGE_NAME }}-${{ matrix.language }}.doccarchive
+          zip -r ${{ env.PACKAGE_NAME }}-${{ matrix.language }}.doccarchive.zip ${{ env.PACKAGE_NAME }}-${{ matrix.language }}.doccarchive
+      - name: Upload DocC Artifact (${{ matrix.language }}) ⬆️
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ env.PACKAGE_NAME }}-${{ matrix.language }}.doccarchive.zip
+          path: ${{ env.PACKAGE_NAME }}-${{ matrix.language }}.doccarchive.zip
+      - name: Upload DocC Archive to GitHub release (${{ matrix.language }}) ⬆️
+        if: github.event.release
+        uses: svenstaro/[email protected]
+        with:
+          file: ${{ env.PACKAGE_NAME }}-${{ matrix.language }}.doccarchive.zip
+          asset_name: ${{ env.PACKAGE_NAME }}-${{ matrix.language }}.doccarchive.zip
+          tag: ${{ github.ref_name }}
+  publish:
+    name: Publish Documentation Site 🛜
+    if: github.event.release.prerelease == false && github.event.release.draft == false && github.event.release.tag_name == github.event.repository.default_branch
+    runs-on: macos-13
+    needs: generate-docc
+    strategy:
+      matrix:
+        language: ['en']
+    steps:
+      - name: Download DocC Archive ⬇️
+        uses: actions/download-artifact@v3
+        with:
+          name: ${{ env.PACKAGE_NAME }}-${{ matrix.language }}.doccarchive.zip
+      - name: Unzip Archive 😮
+        run: |
+          unzip ${{ env.PACKAGE_NAME }}-${{ matrix.language }}.doccarchive.zip
+          ls -li ${{ env.PACKAGE_NAME }}-${{ matrix.language }}.doccarchive
+      - name: lowercase Package Name 🔤
+        id: package-name
+        uses: vishalmamidi/lowercase-action@v1
+        with:
+          string: ${{ env.PACKAGE_NAME }}
+      - name: Build Static Website 🎈
+        run: |
+          $(xcrun --find docc) process-archive \
+            transform-for-static-hosting ${{ env.PACKAGE_NAME }}-en.doccarchive \
+            --hosting-base-path ${{ github.event.repository.name }} \
+            --output-path docs
+          echo "<script>window.location.href += \"/documentation/${{ steps.package-name.outputs.lowercase }}\"</script>" > docs/index.html
+      - name: Upload artifact ⬆️
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'docs'
+      - name: Deploy to GitHub Pages 📑
+        id: deployment
+        uses: actions/deploy-pages@v2
diff --git a/.github/workflows/swiftpm-resolve.yml b/.github/workflows/swiftpm-resolve.yml
@@ -14,6 +14,6 @@ jobs:
   resolve:
     runs-on: macOS-latest
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v3
     - name: Build Package
       run: swift package resolve
diff --git a/.github/workflows/workflow_deploy.yml b/.github/workflows/workflow_deploy.yml
@@ -0,0 +1,91 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy DocC To Pages (en)
+
+on:
+  # Runs on workflow dispatch only
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+env:
+  PACKAGE_NAME: AgoraRtcKit
+  BUILD_DEST: generic/platform=iOS
+  BUILD_PRODUCT: Debug-iphoneos
+  JSON_TEMPLATE_BASE: https://github.com/AgoraIO/agora_doc_source/releases/download/master-build/ios_ng_json_template
+
+jobs:
+  generate-docc:
+    name: Build DocC Archives
+    runs-on: macos-13
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+      - name: Switch Xcode 🔄
+        run: sudo xcode-select --switch /Applications/Xcode_14.3.app
+      - name: Clone DocC Helper 👭
+        uses: actions/checkout@v3
+        with:
+          repository: maxxfrazer/xcframework-to-docc
+          path: xcframework-to-docc
+      - name: Setup Xcode Project 🛠️
+        run: |
+          sh -e xcframework-to-docc/dl_framework.sh ${{ env.PACKAGE_NAME }}
+          sh -e xcframework-to-docc/move_header_files.sh ${{ env.PACKAGE_NAME }}.xcframework ${{ env.PACKAGE_NAME }}.docc
+          sh -e xcframework-to-docc/headers_to_xcodeproj.sh ${{ env.PACKAGE_NAME }} docc_builder
+      - name: Clone Python Script 👭
+        uses: actions/checkout@v3
+        with:
+          repository: littleGnAl/iris-doc
+          path: iris-doc
+      - name: Set up python 3.9 🐍
+        uses: actions/setup-python@v4
+        with:
+            python-version: '3.9'
+      - name: Add Inline Docs (en) 📕
+        run: |
+          cd iris-doc
+          python -m pip install -r requirements.txt
+          python iris_doc.py \
+            --config=$(pwd)/fmt_config/fmt_oc.yaml \
+            --language=oc \
+            --template-url=${{ env.JSON_TEMPLATE_BASE }}_en.json \
+            --export-file-path=$(pwd)/../docc_builder/${{ env.PACKAGE_NAME }}/Headers/${{ env.PACKAGE_NAME }}.h
+      - name: Generate DocC Archive (en) 🪄
+        run: xcodebuild -project docc_builder/${{ env.PACKAGE_NAME }}.xcodeproj docbuild -scheme ${{ env.PACKAGE_NAME }} -derivedDataPath /tmp/docbuild -destination ${{ env.BUILD_DEST }}
+      - name: Zip It Up (en) 🤐
+        run: |
+          mv /tmp/docbuild/Build/Products/${{ env.BUILD_PRODUCT }}/${{ env.PACKAGE_NAME }}.doccarchive ${{ env.PACKAGE_NAME }}-en.doccarchive
+          zip -r ${{ env.PACKAGE_NAME }}-en.doccarchive.zip ${{ env.PACKAGE_NAME }}-en.doccarchive
+      - name: Upload DocC Artifact (en) ⬆️
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ env.PACKAGE_NAME }}-en.doccarchive.zip
+          path: ${{ env.PACKAGE_NAME }}-en.doccarchive.zip
+      - name: lowercase Package Name 🔤
+        id: package-name
+        uses: vishalmamidi/lowercase-action@v1
+        with:
+          string: ${{ env.PACKAGE_NAME }}
+      - name: Build Static Website 🎈
+        run: |
+          $(xcrun --find docc) process-archive \
+            transform-for-static-hosting ${{ env.PACKAGE_NAME }}-en.doccarchive \
+            --hosting-base-path ${{ github.event.repository.name }} \
+            --output-path docs
+          echo "<script>window.location.href += \"/documentation/${{ steps.package-name.outputs.lowercase }}\"</script>" > docs/index.html
+      - name: Upload artifact ⬆️
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'docs'
+      - name: Deploy to GitHub Pages 📑
+        id: deployment
+        uses: actions/deploy-pages@v2
diff --git a/AgoraRtcKit.docc/AgoraRtcEngineKit.md b/AgoraRtcKit.docc/AgoraRtcEngineKit.md
@@ -0,0 +1,46 @@
+# ``AgoraRtcKit/AgoraRtcEngineKit``
+
+## Topics
+
+### Initialise and Destruct
+
+- ``sharedEngine(withAppId:delegate:)``
+- ``sharedEngine(with:delegate:)``
+- ``destroy()``
+
+### Channel Management
+
+- ``joinChannel(byToken:channelId:info:uid:joinSuccess:)``
+- ``joinChannel(byToken:channelId:uid:mediaOptions:joinSuccess:)``
+- ``updateChannel(with:)``
+- ``leaveChannel(_:)``
+- ``leaveChannel(_:leaveChannelBlock:)``
+- ``renewToken(_:)``
+- ``setClientRole(_:options:)``
+- ``setClientRole(_:)``
+- ``getConnectionState()``
+
+### Channel Events
+
+Check out ``AgoraRtcEngineDelegate`` for channel events.
+
+### Audio Management
+
+- ``enableAudio()``
+- ``disableAudio()``
+- ``enableLocalAudio(_:)``
+- ``setAudioProfile(_:)``
+- ``setAudioProfile(_:scenario:)``
+- ``setAudioScenario(_:)``
+- ``muteLocalAudioStream(_:)``
+- ``muteRemoteAudioStream(_:mute:)``
+- ``muteAllRemoteAudioStreams(_:)``
+- ``setAudioSessionOperationRestriction(_:)``
+- ``adjustRecordingSignalVolume(_:)``
+- ``adjustUserPlaybackSignalVolume(_:volume:)``
+- ``adjustCustomAudioPublishVolume(_:volume:)``
+
+### Subscribing to and publishing audio and video streams
+
+- ``setSubscribeAudioBlocklist(_:)``
+- ``setSubscribeAudioAllowlist(_:)``
diff --git a/AgoraRtcKit.docc/AgoraRtcKit.md b/AgoraRtcKit.docc/AgoraRtcKit.md
@@ -0,0 +1,35 @@
+# ``AgoraRtcKit``
+
+Summary
+
+## Overview
+
+AgoraRtcKit provides a wide range of features and tools for building reliable and high-quality audio communication applications. Some of its key features include:
+
+- High-quality audio communication with low latency
+- Support for multiple platforms and devices, including mobile and web
+- Advanced audio processing capabilities, such as noise suppression and echo cancellation
+- Easy integration with third-party tools and services, such as recording and streaming platforms
+
+AgoraRtcKit is designed to be flexible and customizable, allowing developers to tailor their applications to their specific needs and requirements.
+
+## Topics
+
+### Getting Started
+
+- <doc:Channels>
+
+### Core Classes
+
+- ``AgoraRtcKit/AgoraRtcEngineKit``
+- ``AgoraRtcVideoCanvas``
+- ``AgoraRtcEngineDelegate``
+- ``AgoraRtcEngineConfig``
+
+### Advanced Classes
+
+- ``AgoraRtcLocalAudioStats``
+- ``AgoraAudioEffectPreset``
+- ``AgoraEncryptionConfig``
+- ``AgoraVideoFrame``
+
diff --git a/AgoraRtcKit.docc/Channels.md b/AgoraRtcKit.docc/Channels.md
@@ -0,0 +1,44 @@
+# Channels
+
+Joining channels, leaving channels, and everything inbetween.
+
+## Overview
+
+The ins-and-outs of managing your connection to Audio channels with Agora.
+
+## Channel Management
+
+For joining, leaving, and updating channel information, here are some of the most useful functions:
+
+- ``AgoraRtcEngineKit/joinChannel(byToken:channelId:uid:mediaOptions:joinSuccess:)``
+- ``AgoraRtcEngineKit/updateChannel(with:)``
+- ``AgoraRtcEngineKit/leaveChannel(_:)``
+- ``AgoraRtcEngineKit/setClientRole(_:options:)``
+- ``AgoraRtcEngineKit/getConnectionState()``
+
+## Channel Events
+
+``AgoraRtcEngineDelegate`` contians all the callbacks needed for updates to your channel, such as other members joining, leaving, network chnages, and when your token is soon to expire.
+
+Here are a collection of some of the most frequently used delegate methods, but see more in ``AgoraRtcEngineDelegate``.
+
+- ``AgoraRtcEngineDelegate/rtcEngine(_:didJoinChannel:withUid:elapsed:)``
+- ``AgoraRtcEngineDelegate/rtcEngine(_:didRejoinChannel:withUid:elapsed:)``
+- ``AgoraRtcEngineDelegate/rtcEngine(_:didClientRoleChanged:newRole:newRoleOptions:)``
+- ``AgoraRtcEngineDelegate/rtcEngine(_:didClientRoleChangeFailed:currentRole:)``
+- ``AgoraRtcEngineDelegate/rtcEngine(_:didLeaveChannelWith:)``
+- ``AgoraRtcEngineDelegate/rtcEngine(_:didJoinedOfUid:elapsed:)``
+- ``AgoraRtcEngineDelegate/rtcEngine(_:didOfflineOfUid:reason:)``
+- ``AgoraRtcEngineDelegate/rtcEngine(_:networkTypeChanged:)``
+- ``AgoraRtcEngineDelegate/rtcEngine(_:uplinkNetworkInfoUpdate:)``
+- ``AgoraRtcEngineDelegate/rtcEngineConnectionDidLost(_:)``
+- ``AgoraRtcEngineDelegate/rtcEngine(_:connectionChangedTo:reason:)``
+- ``AgoraRtcEngineDelegate/rtcEngineRequestToken(_:)``
+- ``AgoraRtcEngineDelegate/rtcEngine(_:tokenPrivilegeWillExpire:)``
+- ``AgoraRtcEngineDelegate/rtcEngine(_:didOccurError:)``
+
+## Multiple Channel Connections
+
+With AgoraRtcKit, you're able to join multiple channels. The best way to join a secondary channel as an audience member (not broadcasting), is using this join method:
+
+- ``AgoraRtcEngineKit/joinChannelEx(byToken:connection:delegate:mediaOptions:joinSuccess:)``