docs: Build-test documentation in the CI and fix/improve broken links (…

…#455)

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.

.github/workflows/ci.yml

@@ -159,3 +159,29 @@ jobs:
         with:
           directory: coverage
           #files: lcov.info
+
+  doc:
+    name: Build-test documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v2
+
+      - name: Install rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+          components: rust-docs
+
+      - uses: Swatinem/rust-cache@v1
+
+      - name: Run cargo doc
+        uses: actions-rs/cargo@v1
+        env:
+          RUSTDOCFLAGS: -Dwarnings
+        with:
+          command: doc
+          args: --workspace --all-features --no-deps --document-private-items

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;
 }
 

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")]

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

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,

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,

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,