Auto merge of #256 - troy/docs, r=lennartkloock

Auto Deploy Docs setup auto deployment for docs so we can preview prs and keep the `main` branch docs up-to-date Requested-by: TroyKomodo <[email protected]> Reviewed-by: lennartkloock <[email protected]>
ScuffleCloud · Jan 16, 2025 · e87073a · e87073a
2 parents 6b90da7 + f409246
commit e87073a
Show file tree

Hide file tree

Showing 19 changed files with 133 additions and 44 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -14,13 +14,19 @@ concurrency:
 
 env:
   RUST_TOOLCHAIN: nightly
+  # By default, when a action is run against a PR it will use a merge commit from the target branch & the PR branch. We want to use just the PR branch.
+  # So this changes the SHA to the PR branch SHA or falls back to the current SHA (if its not a PR)
+  # https://github.com/actions/checkout/issues/426
+  SHA: ${{ github.event.pull_request.head.sha || github.sha }}
 
 jobs:
   clippy:
     name: Clippy
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.SHA }}
 
       - name: Setup nasm
         run: |
@@ -48,6 +54,8 @@ jobs:
       checks: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.SHA }}
 
       - uses: dtolnay/rust-toolchain@stable
         id: setup-rust
@@ -63,6 +71,8 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.SHA }}
 
       - uses: dtolnay/rust-toolchain@stable
         id: setup-rust
@@ -86,6 +96,8 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.SHA }}
 
       - name: Setup nasm
         run: |
@@ -149,7 +161,7 @@ jobs:
           files: ./lcov.info
           token: ${{ secrets.CODECOV_TOKEN }}
           override_pr: ${{ env.PR_NUMBER || github.event.pull_request.number || '' }}
-          override_commit: ${{ env.RUN_COMMIT_SHA || github.sha }}
+          override_commit: ${{ env.RUN_COMMIT_SHA || env.SHA }}
           verbose: true
 
       - name: Upload test results to Codecov
@@ -158,12 +170,63 @@ jobs:
         with:
           files: ./target/nextest/ci/junit.xml
           override_pr: ${{ env.PR_NUMBER || github.event.pull_request.number || '' }}
-          override_commit: ${{ env.RUN_COMMIT_SHA || github.sha }}
+          override_commit: ${{ env.RUN_COMMIT_SHA || env.SHA }}
           token: ${{ secrets.CODECOV_TOKEN }}
 
+  docs:
+    name: Docs
+    runs-on: ubuntu-24.04
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.SHA }}
+
+      - name: Setup nasm
+        run: |
+          sudo apt-get install nasm
+
+      - uses: dtolnay/rust-toolchain@stable
+        id: setup-rust
+        with:
+          toolchain: ${{ env.RUST_TOOLCHAIN }}
+          components: rust-docs
+
+      - uses: Swatinem/rust-cache@v2
+        id: cache-rust
+        with:
+          prefix-key: "v0-rust-${{ steps.setup-rust.outputs.cachekey }}"
+          shared-key: docs
+
+      - name: Build docs
+        run: |
+          RUSTDOCFLAGS="-D warnings --cfg docsrs --enable-index-page -Zunstable-options" cargo +${{ env.RUST_TOOLCHAIN }} doc --no-deps --all-features
+
+      - name: Upload docs
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: target/doc
+
+      - name: Get PR Number
+        if: ${{ startsWith(github.ref, 'refs/heads/automation/brawl/try/') }}
+        run: |
+          PR_NUMBER=$(echo ${{ github.ref }} | sed -n 's/^refs\/heads\/automation\/brawl\/try\/\([0-9]*\)$/\1/p')
+          echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
+
+      - name: Deploy
+        if: ${{ startsWith(github.ref, 'refs/heads/automation/brawl/try/') || github.event.pull_request.head.repo.full_name == github.repository }}
+        id: deploy
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CF_DOCS_API_KEY }}
+          accountId: ${{ secrets.CF_DOCS_ACCOUNT_ID }}
+          command: pages deploy --project-name=scuffle-docrs --branch=pr/${{ env.PR_NUMBER || github.event.pull_request.number }} --commit-hash=${{ env.SHA }} ./target/doc
+
   brawl-done:
     runs-on: ubuntu-24.04
-    needs: [hakari, test, clippy, fmt]
+    needs: [hakari, test, clippy, fmt, docs]
     if: ${{ !cancelled() && github.event_name == 'push' }}
     steps:
       - name: calculate the correct exit status

diff --git a/.github/workflows/docs-release.yaml b/.github/workflows/docs-release.yaml
@@ -0,0 +1,33 @@
+name: Docs Release
+
+on:
+  push:
+    branches:
+      - main
+      - test-deploy
+
+jobs:
+  docs:
+    name: Docs
+    runs-on: ubuntu-24.04
+    environment: docs.scuffle.rs
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download Artifact
+        id: download-artifact
+        uses: dawidd6/action-download-artifact@v7
+        with:
+          workflow: ci.yaml
+          workflow_conclusion: success
+          commit: ${{ github.sha }}
+          name: docs
+          path: target/doc
+
+      - name: Deploy
+        id: deploy
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CF_DOCS_API_KEY }}
+          accountId: ${{ secrets.CF_DOCS_ACCOUNT_ID }}
+          command: pages deploy --project-name=scuffle-docrs --branch=main --commit-hash=${{ github.sha }} ./target/doc
diff --git a/Justfile b/Justfile
@@ -1,5 +1,6 @@
 mod? local
 
+
 # By default we use the nightly toolchain, however you can override this by setting the RUST_TOOLCHAIN environment variable.
 export RUST_TOOLCHAIN := env_var_or_default('RUST_TOOLCHAIN', 'nightly')
 
@@ -29,8 +30,17 @@ test *args:
     cargo +{{RUST_TOOLCHAIN}} llvm-cov report --lcov --output-path ./lcov.info
     cargo +{{RUST_TOOLCHAIN}} llvm-cov report --html
 
+alias docs := doc
 doc *args:
-    cargo +{{RUST_TOOLCHAIN}} doc --no-deps --all-features {{args}}
+    # `--cfg docsrs` enables us to write feature hints in the form of `#[cfg_attr(docsrs, doc(cfg(feature = "some-feature")))]`
+    # `--enable-index-page` makes the command generate an index page which lists all crates (unstable)
+    # `-D warnings` disallow all warnings
+    # `-Zunstable-options` enables unstable options (for the `--enable-index-page` flag)
+    RUSTDOCFLAGS="-D warnings --cfg docsrs --enable-index-page -Zunstable-options" cargo +{{RUST_TOOLCHAIN}} doc --no-deps --all-features {{args}}
+
+alias docs-serve := doc-serve
+doc-serve: doc
+    miniserve target/doc --index index.html --port 3000
 
 deny *args:
     cargo +{{RUST_TOOLCHAIN}} deny {{args}} --all-features check

diff --git a/crates/av1/src/config.rs b/crates/av1/src/config.rs
@@ -5,7 +5,7 @@ use scuffle_bytes_util::{BitReader, BitWriter, BytesCursorExt};
 
 #[derive(Debug, Clone, PartialEq)]
 /// AV1 Codec Configuration Record
-/// https://aomediacodec.github.io/av1-isobmff/#av1codecconfigurationbox-syntax
+/// <https://aomediacodec.github.io/av1-isobmff/#av1codecconfigurationbox-syntax>
 pub struct AV1CodecConfigurationRecord {
     pub seq_profile: u8,
     pub seq_level_idx_0: u8,

diff --git a/crates/bootstrap/src/service.rs b/crates/bootstrap/src/service.rs
@@ -36,16 +36,14 @@ pub trait Service<Global>: Send + Sync + 'static + Sized {
     /// service should stop as soon as the provided context is done.
     ///
     /// Note: Adding the
-    /// [`scuffle_signal::SignalSvc`](../../scuffle_signal/struct.SignalSvc.
-    /// html) service to the list of services when calling
-    /// [`main`](crate::main) will cancel the context as soon as a shutdown
-    /// signal is received.
+    /// [`scuffle_signal::SignalSvc`](../../scuffle_signal/struct.SignalSvc.html)
+    /// service to the list of services when calling [`main`](crate::main) will
+    /// cancel the context as soon as a shutdown signal is received.
     ///
     /// # See Also
     ///
     /// - [`Context`](scuffle_context::Context)
-    /// - [`scuffle_signal::SignalSvc`](../../scuffle_signal/struct.SignalSvc.
-    ///   html)
+    /// - [`scuffle_signal::SignalSvc`](../../scuffle_signal/struct.SignalSvc.html)
     fn run(
         self,
         global: Arc<Global>,

diff --git a/crates/ffmpeg/src/lib.rs b/crates/ffmpeg/src/lib.rs
@@ -1,5 +1,3 @@
-#![doc = include_str!("../README.md")]
-
 pub mod codec;
 pub mod consts;
 pub mod decoder;

diff --git a/crates/future-ext/src/lib.rs b/crates/future-ext/src/lib.rs
@@ -1,6 +1,6 @@
 /// The [`FutureExt`] trait is a trait that provides a more ergonomic way to
-/// extend futures with additional functionality. Similar to the [`IteratorExt`]
-/// trait, but for futures.
+/// extend futures with additional functionality. Similar to the `IteratorExt`
+/// trait from the `itertools` crate, but for futures.
 pub trait FutureExt {
     /// Attach a timeout to the future.
     ///

diff --git a/crates/h3-webtransport/src/lib.rs b/crates/h3-webtransport/src/lib.rs
@@ -3,8 +3,7 @@
 //! # Relevant Links
 //! WebTransport: <https://www.w3.org/TR/webtransport/#biblio-web-transport-http3>
 //! WebTransport over HTTP/3: <https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/>
-#![deny(missing_docs)]
-#![doc = include_str!("../README.md")]
+// #![deny(missing_docs)]
 
 /// A WebTransport server
 pub mod server;

diff --git a/crates/h3-webtransport/src/server.rs b/crates/h3-webtransport/src/server.rs
@@ -116,15 +116,15 @@ where
     },
 }
 
-/// A WebTransport server that allows incoming requests to be upgraded to
-/// `WebTransportSessions`
-///
-/// The [`WebTransportServer`] struct manages a connection from the side of the
-/// HTTP/3 server
-///
-/// Create a new Instance with [`WebTransportServer::new()`].
-/// Accept incoming requests with [`WebTransportServer::accept()`].
-/// And shutdown a connection with [`WebTransportServer::shutdown()`].
+// A WebTransport server that allows incoming requests to be upgraded to
+// `WebTransportSessions`
+//
+// The [`WebTransportServer`] struct manages a connection from the side of the
+// HTTP/3 server
+//
+// Create a new Instance with [`WebTransportServer::new()`].
+// Accept incoming requests with [`WebTransportServer::accept()`].
+// And shutdown a connection with [`WebTransportServer::shutdown()`].
 pub struct Connection<C, B>
 where
     C: quic::Connection<B>,

diff --git a/crates/http/src/lib.rs b/crates/http/src/lib.rs
@@ -1,5 +1,3 @@
-#![doc = include_str!("../README.md")]
-
 pub mod backend;
 pub mod body;
 pub mod builder;

diff --git a/crates/metrics/derive/src/lib.rs b/crates/metrics/derive/src/lib.rs
@@ -1,5 +1,3 @@
-#![doc = include_str!("../README.md")]
-
 use enum_impl::metric_enum_impl;
 use metrics_impl::metrics_impl;
 use proc_macro::TokenStream;

diff --git a/crates/metrics/src/lib.rs b/crates/metrics/src/lib.rs
@@ -1,5 +1,3 @@
-#![doc = include_str!("../README.md")]
-
 #[cfg(feature = "prometheus")]
 /// A copy of the opentelemetry-prometheus crate, updated to work with the
 /// latest version of opentelemetry.

diff --git a/crates/mp4/src/boxes/types/av01.rs b/crates/mp4/src/boxes/types/av01.rs
@@ -15,7 +15,7 @@ use crate::codec::VideoCodec;
 
 #[derive(Debug, Clone, PartialEq)]
 /// AV1 Codec Box
-/// https://aomediacodec.github.io/av1-isobmff/#av1sampleentry-section
+/// <https://aomediacodec.github.io/av1-isobmff/#av1sampleentry-section>
 pub struct Av01 {
     pub header: BoxHeader,
     pub visual_sample_entry: SampleEntry<VisualSampleEntry>,

diff --git a/crates/mp4/src/boxes/types/av1c.rs b/crates/mp4/src/boxes/types/av1c.rs
@@ -8,7 +8,7 @@ use crate::boxes::traits::BoxType;
 
 #[derive(Debug, Clone, PartialEq)]
 /// AV1 Configuration Box
-/// https://aomediacodec.github.io/av1-isobmff/#av1codecconfigurationbox-section
+/// <https://aomediacodec.github.io/av1-isobmff/#av1codecconfigurationbox-section>
 pub struct Av1C {
     pub header: BoxHeader,
     pub av1_config: AV1CodecConfigurationRecord,

diff --git a/crates/mp4/src/codec.rs b/crates/mp4/src/codec.rs
@@ -5,10 +5,10 @@ use scuffle_aac::AudioObjectType;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum VideoCodec {
-    /// https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter
+    /// <https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter>
     Avc { profile: u8, constraint_set: u8, level: u8 },
     /// There is barely any documentation on this.
-    /// http://hevcvideo.xp3.biz/html5_video.html
+    /// <https://hevcvideo.xp3.biz/html5_video.html>
     Hevc {
         general_profile_space: u8,
         profile_compatibility: u32,
@@ -17,7 +17,7 @@ pub enum VideoCodec {
         tier: bool,
         constraint_indicator: u64,
     },
-    /// https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#av1
+    /// <https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#av1>
     Av1 {
         profile: u8,
         level: u8,

diff --git a/crates/postcompile/src/lib.rs b/crates/postcompile/src/lib.rs
@@ -1,5 +1,3 @@
-#![doc = include_str!("../README.md")]
-
 use std::borrow::Cow;
 use std::ffi::{OsStr, OsString};
 use std::os::unix::ffi::OsStrExt;

diff --git a/crates/pprof/src/lib.rs b/crates/pprof/src/lib.rs
@@ -1,5 +1,3 @@
-#![doc = include_str!("../README.md")]
-
 mod cpu;
 
 #[derive(Debug, thiserror::Error)]

diff --git a/crates/settings/src/lib.rs b/crates/settings/src/lib.rs
@@ -1,5 +1,3 @@
-#![doc = include_str!("../README.md")]
-
 use std::path::Path;
 
 #[derive(Debug, thiserror::Error)]

diff --git a/rustfmt.toml b/rustfmt.toml
@@ -2,7 +2,7 @@ imports_granularity = "Module"
 newline_style = "Unix"
 normalize_comments = true
 group_imports = "StdExternalCrate"
-wrap_comments = true
+wrap_comments = false
 style_edition = "2021"
 format_macro_matchers = true
 reorder_impl_items = true