docs: add Netlify auto-publishing of main API docs (console-rs#116)

This branch configures Netlify to automatically build and publish the
API docs for the `main` branch. This is particularly useful right now,
since the console hasn't been published to `crates.io`, so we don't have
docs.rs docs to refer people to yet. A deploy preview is also generated
for every pull request against `main`, so we can preview the new docs
added in PRs.

Since I configured the Netlify docs build to deny RustDoc warnings, I
also had to fix a couple broken links in the current docs.

The `console` crate's docs are built with private items included. This
is because the `console` application is a binary rather than a library, and
will probably never be published as a lib. Those docs should be thought
of as internal development docs, rather than user-facing API reference
docs.

Signed-off-by: Eliza Weisman <[email protected]>

Author: hawkw

README.md

@@ -1,11 +1,17 @@
 # tokio-console prototypes
 
+[![API Documentation (`main`)](https://img.shields.io/netlify/0e5ffd50-e1fa-416e-b147-a04dab28cfb1?label=docs%20%28main%29)][main-docs]
+
 ⚠️ **extremely serious warning:** this is _pre-alpha_, proof-of-concept
 software! currently, the wire format has _no stability guarantees_ —
 the crates in this repository are not guaranteed to be interoperable except
 within the same Git revision. when these crates are published to crates.io, the
 wire format will follow semver, but currently, anything could happen!
 
+[API Documentation (`main` branch)][main-docs]
+
+[main-docs]: https://tokio-console.netlify.app
+
 ## what's all this, then?
 
 this repository contains a prototype implementation of TurboWish/tokio-console,

console-subscriber/src/init.rs

@@ -50,10 +50,11 @@ pub fn init() {
 /// and a [filter] that enables the spans and events required by the console.
 ///
 /// Unlike [`init`], this function does not set the default subscriber, allowing
-/// additional [`Layer`s] to be added.
+/// additional [`Layer`]s to be added.
 ///
 /// [subscriber]: https://docs.rs/tracing/latest/tracing/subscriber/trait.Subscriber.html
 /// [filter]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html
+/// [`Layer`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/layer/trait.Layer.html
 ///
 /// ## Configuration
 ///
@@ -62,9 +63,8 @@ pub fn init() {
 ///
 /// ## Differences from `init`
 ///
-/// You must call
-/// [`init`][tracing_subscriber::util::SubscriberInitExt::init] on the
-/// final layer in order to register the subscriber.
+/// You must call [`.init()`] on the final subscriber in order to [set the
+/// subscriber as the default][set_default].
 ///
 /// ## Examples
 ///
@@ -75,7 +75,8 @@ pub fn init() {
 /// //  .with(...)
 ///     .init();
 /// ```
-
+/// [`.init()`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/util/trait.SubscriberInitExt.html
+/// [set_default]: https://docs.rs/tracing/latest/tracing/subscriber/fn.set_default.html
 #[must_use = "build() without init() will not set the default tracing subscriber"]
 pub fn build() -> ConsoleSubscriberLayer {
     let (layer, server) = TasksLayer::builder().with_default_env().build();

console/src/view/mini_histogram.rs

@@ -9,7 +9,10 @@ use tui::{
 
 /// This is a tui-rs widget to visualize a latency histogram in a small area.
 /// It is based on the [`Sparkline`] widget, so it draws a mini bar chart with
-/// some labels for clarity. Unlike Sparkline, it does not omit very small values.
+/// some labels for clarity. Unlike Sparkline, it does not omit very small
+/// values.
+///
+/// [`Sparkline`]: tui::widgets::Sparkline
 pub(crate) struct MiniHistogram<'a> {
     /// A block to wrap the widget in
     block: Option<Block<'a>>,

netlify.toml

@@ -0,0 +1,12 @@
+[build]
+  command = """
+    rustup install nightly --profile minimal \
+        && cargo doc --no-deps --all-features -p console-subscriber -p console-api \
+        && cargo doc --no-deps --all-features --document-private-items -p console
+    """
+  environment = { RUSTDOCFLAGS= "--cfg docsrs -D warnings" }
+  publish = "target/doc"
+
+[[redirects]]
+  from = "/"
+  to = "/console_subscriber"