add workflow to generate the docs and upload the docs (#48)

* add workflow to generate the docs and upload the docs

* remove the comments

* fix the aws access variables

Author: xianshijing-lk

.github/workflows/make-release.yml

@@ -285,3 +285,10 @@ jobs:
           generate_release_notes: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # ---------- Publish Docs Job ----------
+  publish-docs:
+    name: Publish Documentation
+    needs: release
+    uses: ./.github/workflows/publish-docs.yml
+    secrets: inherit

.github/workflows/publish-docs.yml

@@ -0,0 +1,48 @@
+name: Publish docs
+
+on:
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+          lfs: true
+
+      # Doxygen is available on ubuntu-latest, but we install explicitly for stability
+      - name: Install Doxygen
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen graphviz
+
+      - name: Build Docs (Doxygen)
+        run: |
+          doxygen docs/Doxyfile
+
+      - name: S3 Upload
+        run: |
+          DOCS_DIR="html"
+          if [[ ! -d "$DOCS_DIR" ]]; then
+            echo "Expected docs at $DOCS_DIR but directory not found."
+            exit 1
+          fi
+
+          # Upload to rolling latest (no versioned docs, always overwrite)
+          aws s3 sync "$DOCS_DIR"/ s3://livekit-docs/cpp --delete
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_DEFAULT_REGION: "us-east-1"
+
+      - name: Expire cloudfront cache
+        run: |
+          aws cloudfront create-invalidation --distribution-id EJJ40KLJ3TRY9 --paths "/cpp/*"
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_DEFAULT_REGION: "us-east-1"
+

docs/Doxyfile

@@ -27,6 +27,8 @@
 # Project related configuration options
 #---------------------------------------------------------------------------
 
+PROJECT_NAME = "LiveKit C++ SDK"
+
 # This tag specifies the encoding used for all characters in the configuration
 # file that follow. The default is UTF-8 which is also the encoding used for all
 # text before the first occurrence of this tag. Doxygen uses libiconv (or the
@@ -1005,7 +1007,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT = ../include/livekit ../docs/index.md ../README.md ../examples/simple_rpc/README.md
+INPUT = include/livekit docs/index.md README.md examples/simple_rpc/README.md
 
 # This tag can be used to specify the character encoding of the source files
 # that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1220,7 +1222,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the Doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = docs/index.md
 
 # If the IMPLICIT_DIR_DOCS tag is set to YES, any README.md file found in sub-
 # directories of the project's root, is used as the documentation for that sub-
@@ -1429,8 +1431,8 @@ HTML_STYLESHEET        =
 # documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  = customization/doxygen-awesome.css \
-                          customization/custom.css
+HTML_EXTRA_STYLESHEET  = docs/customization/doxygen-awesome.css \
+                          docs/customization/custom.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -2605,7 +2607,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # set to NO
 # The default value is: NO.
 
-HAVE_DOT               = NO
+HAVE_DOT               = YES
 
 # The DOT_NUM_THREADS specifies the number of dot invocations Doxygen is allowed
 # to run in parallel. When set to 0 Doxygen will base this on the number of

include/livekit/audio_frame.h

@@ -27,6 +27,13 @@ class AudioFrameBufferInfo;
 class OwnedAudioFrameBuffer;
 } // namespace proto
 
+/**
+ * @brief Represents a raw PCM audio frame with interleaved int16 samples.
+ *
+ * AudioFrame holds decoded audio data along with metadata such as sample rate,
+ * number of channels, and samples per channel. It is used for capturing and
+ * processing audio in the LiveKit SDK.
+ */
 class AudioFrame {
 public:
   /**

include/livekit/audio_stream.h

@@ -35,8 +35,14 @@ namespace proto {
 class FfiEvent;
 }
 
+/**
+ * @brief Event containing an audio frame received from an AudioStream.
+ *
+ * This struct wraps an AudioFrame and is used as the output type when
+ * reading from an AudioStream.
+ */
 struct AudioFrameEvent {
-  AudioFrame frame;
+  AudioFrame frame; ///< The decoded PCM audio frame.
 };
 
 /**

include/livekit/stats.h

@@ -293,13 +293,21 @@ struct VideoSourceStats {
   double frames_per_second;
 };
 
+/**
+ * @brief Statistics for audio playout performance.
+ *
+ * Contains metrics about audio sample synthesis and playout timing,
+ * useful for monitoring audio quality and detecting issues like underruns.
+ */
 struct AudioPlayoutStats {
-  std::string kind;
-  double synthesized_samples_duration;
-  std::uint32_t synthesized_samples_events;
-  double total_samples_duration;
-  double total_playout_delay;
-  std::uint64_t total_samples_count;
+  std::string kind;                    ///< The type of media ("audio").
+  double synthesized_samples_duration; ///< Duration of synthesized samples in
+                                       ///< seconds.
+  std::uint32_t synthesized_samples_events; ///< Number of synthesis events
+                                            ///< (e.g., concealment).
+  double total_samples_duration; ///< Total duration of all samples in seconds.
+  double total_playout_delay;    ///< Cumulative playout delay in seconds.
+  std::uint64_t total_samples_count; ///< Total number of samples played out.
 };
 
 struct PeerConnectionStats {