add docs build commands

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

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,

crates/bootstrap/src/service.rs

@@ -36,16 +36,15 @@ 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
+    /// <a href="../../scuffle_signal/struct.SignalSvc.html">`scuffle_signal::SignalSvc`</a>
+    /// 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)
+    /// - <a href="../../scuffle_signal/struct.SignalSvc.html">`scuffle_signal::SignalSvc`</a>
     fn run(
         self,
         global: Arc<Global>,

crates/ffmpeg/src/lib.rs

@@ -1,5 +1,3 @@
-#![doc = include_str!("../README.md")]
-
 pub mod codec;
 pub mod consts;
 pub mod decoder;

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.
     ///

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;

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>,

crates/http/src/lib.rs

@@ -1,5 +1,3 @@
-#![doc = include_str!("../README.md")]
-
 pub mod backend;
 pub mod body;
 pub mod builder;

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;

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.

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>,

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,

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,

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;

crates/pprof/src/lib.rs

@@ -1,5 +1,3 @@
-#![doc = include_str!("../README.md")]
-
 mod cpu;
 
 #[derive(Debug, thiserror::Error)]

crates/settings/src/lib.rs

@@ -1,5 +1,3 @@
-#![doc = include_str!("../README.md")]
-
 use std::path::Path;
 
 #[derive(Debug, thiserror::Error)]