Build-test documentation in the CI and fix/improve broken links

Some intradoc links were broken because their crates are only available as `dev-dependencies`, while others unnecessarily had a forced link to `docs.rs` which could also be an intradoc link (in turn pointing to locally built documentation if not building on docs.rs). To make sure these links don't break again over time, build-test the documentation in the CI while disallowing any warnings which includes broken links.
getsentry · Apr 8, 2022 · d67395b · d67395b
1 parent 62f7b8e
commit d67395b
Show file tree

Hide file tree

Showing 7 changed files with 38 additions and 10 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -159,3 +159,35 @@ jobs:
         with:
           directory: coverage
           #files: lcov.info
+
+  doc:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        rust: [nightly]
+
+    name: Build-test documentation using Rust ${{ matrix.rust }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v2
+
+      - name: Install rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: ${{ matrix.rust }}
+          override: true
+          components: rust-docs
+
+      - uses: Swatinem/rust-cache@v1
+
+      - name: Run cargo doc
+        uses: actions-rs/cargo@v1
+        env:
+          RUSTDOCFLAGS: -Dwarnings --cfg doc_cfg
+        with:
+          command: doc
+          args: --workspace --all-features --no-deps --document-private-items
diff --git a/sentry-anyhow/src/lib.rs b/sentry-anyhow/src/lib.rs
@@ -59,12 +59,8 @@ pub fn capture_anyhow(e: &anyhow::Error) -> Uuid {
 }
 
 /// Hub extension methods for working with [`anyhow`].
-///
-/// [`anyhow`]: https://docs.rs/anyhow
 pub trait AnyhowHubExt {
     /// Captures an [`anyhow::Error`] on a specific hub.
-    ///
-    /// [`anyhow::Error`]: https://docs.rs/anyhow/*/anyhow/struct.Error.html
     fn capture_anyhow(&self, e: &anyhow::Error) -> Uuid;
 }
 

diff --git a/sentry-tower/src/lib.rs b/sentry-tower/src/lib.rs
@@ -127,6 +127,8 @@
 //!     .layer(sentry_tower::SentryHttpLayer::with_transaction());
 //! # }
 //! ```
+//!
+//! [`tower::ServiceBuilder`]: https://docs.rs/tower/latest/tower/struct.ServiceBuilder.html
 
 #![doc(html_favicon_url = "https://sentry-brand.storage.googleapis.com/favicon.ico")]
 #![doc(html_logo_url = "https://sentry-brand.storage.googleapis.com/sentry-glyph-black.png")]

diff --git a/sentry-tracing/src/layer.rs b/sentry-tracing/src/layer.rs
@@ -94,6 +94,8 @@ impl<S> SentryLayer<S> {
     ///
     /// The filter classifies whether sentry should handle [`tracing::Span`]s based
     /// on their [`Metadata`].
+    ///
+    /// [`tracing::Span`]: https://docs.rs/tracing/latest/tracing/struct.Span.html
     #[must_use]
     pub fn span_filter<F>(mut self, filter: F) -> Self
     where

diff --git a/sentry/src/transports/curl.rs b/sentry/src/transports/curl.rs
@@ -10,8 +10,6 @@ use crate::{sentry_debug, types::Scheme, ClientOptions, Envelope, Transport};
 /// A [`Transport`] that sends events via the [`curl`] library.
 ///
 /// This is enabled by the `curl` feature flag.
-///
-/// [`curl`]: https://crates.io/crates/curl
 #[cfg_attr(doc_cfg, doc(cfg(feature = "curl")))]
 pub struct CurlHttpTransport {
     thread: TransportThread,

diff --git a/sentry/src/transports/reqwest.rs b/sentry/src/transports/reqwest.rs
@@ -12,7 +12,7 @@ use crate::{sentry_debug, ClientOptions, Envelope, Transport};
 /// be the default transport.  This is separately enabled by the
 /// `reqwest` feature flag.
 ///
-/// [`reqwest`]: https://crates.io/crates/reqwest
+/// [`reqwest`]: reqwest_
 #[cfg_attr(doc_cfg, doc(cfg(feature = "reqwest")))]
 pub struct ReqwestHttpTransport {
     thread: TransportThread,

diff --git a/sentry/src/transports/ureq.rs b/sentry/src/transports/ureq.rs
@@ -1,6 +1,6 @@
 use std::time::Duration;
 
-#[cfg(fdoc)]
+#[cfg(doc)]
 use ureq_ as ureq;
 use ureq_::{Agent, AgentBuilder, Proxy};
 
@@ -11,8 +11,6 @@ use crate::{sentry_debug, types::Scheme, ClientOptions, Envelope, Transport};
 /// A [`Transport`] that sends events via the [`ureq`] library.
 ///
 /// This is enabled by the `ureq` feature flag.
-///
-/// [`ureq`]: https://crates.io/crates/ureq
 #[cfg_attr(doc_cfg, doc(cfg(feature = "ureq")))]
 pub struct UreqHttpTransport {
     thread: TransportThread,