chore: update tokio-console screenshots for v0.1.13 (#591)

The screenshots on the docs.rs page for tokio-console are a bit out of
date. They are from v0.1.8 and still show the Target column instead of
the Kind column.

With the task size instrumentation and new lints which will be released
in the next version of Tokio Console, we need screenshots which match
what the user will see. The same goes for the screenshots in the
repository root README.md, which anyone visiting the repo page on GitHub
will see.

This change adds new screenshots for docs.rs and replaces the README
screenshots. We have to keep the docs.rs images from previous versions
still, since docs.rs pages for previous versions still reference them.

Additionally, a new CI job to build the docs.rs documentation and also
to check that all the images referenced from the tokio-console README
file (which is used on docs.rs) are present in the repository, as we
can't inspect the documentation until the change is merged. This is done
via a new `xtask` operation.

.github/workflows/ci.yml

@@ -101,6 +101,23 @@ jobs:
       - name: Run cargo clippy
         run: cargo clippy --workspace --all-targets --no-deps -- -D warnings
 
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+
+      - name: Install ${{ matrix.rust }} toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Run xtask check-docs-images
+        run: cargo run --bin xtask -- check-docs-images
+
   grpc_web:
     name: gRPC-web Example
     runs-on: ubuntu-latest

tokio-console/README.md

@@ -121,7 +121,7 @@ tokio-console --lang en_US.UTF-8
 When the console CLI is launched, it displays a list of all [asynchronous tasks]
 in the program:
 
-![tasks list](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.8/tasks_list.png)
+![tasks list](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.13/tasks_list.png)
 
 Tasks are displayed in a table.
 
@@ -154,7 +154,7 @@ task.
 
 This view shows details about a specific task:
 
-![task details](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.8/task_details.png)
+![task details](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.13/task_details.png)
 
 The task details view includes percentiles and a visual histogram of the polling (busy) times
 and scheduled times.
@@ -166,7 +166,7 @@ Pressing the <kbd>escape</kbd> key returns to the task list.
 The <kbd>r</kbd> key switches from the list of tasks to a list of [resources],
 such as synchronization primitives, I/O resources, et cetera:
 
-![resource list](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.8/resources_list.png)
+![resource list](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.13/resources_list.png)
 
 Resources are displayed in a table similar to the task list.
 
@@ -192,13 +192,13 @@ while a resource is highlighted displays details about that resource.
 
 ### Resource Details
 
-![resource details --- sleep](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.8/resource_details_sleep.png)
+![resource details --- sleep](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.13/resource_details_sleep.png)
 
 The resource details view lists the tasks currently waiting on that resource.
 This may be a single task, as in the [`tokio::time::Sleep`] above, or
 a large number of tasks, such as this private `tokio::sync::batch_semaphore::Semaphore`:
 
-![resource details --- semaphore](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.8/resource_details_semaphore.png)
+![resource details --- semaphore](https://raw.githubusercontent.com/tokio-rs/console/main/assets/tokio-console-0.1.13/resource_details_semaphore.png)
 
 The resource details view includes a table of async ops belonging to the resource.
 

xtask/Cargo.toml

@@ -12,3 +12,4 @@ tonic-build = { version = "0.12", default-features = false, features = [
 ] }
 clap = { version = "~4.5.4", features = ["derive"] }
 color-eyre = "0.6"
+regex = "1.11.0"

xtask/src/main.rs

@@ -1,9 +1,16 @@
+use std::{
+    fmt::Write,
+    fs,
+    io::{BufRead, BufReader},
+    path::{Path, PathBuf},
+};
+
 use clap::Parser;
 use color_eyre::{
-    eyre::{ensure, WrapErr},
+    eyre::{ensure, eyre, WrapErr},
     Result,
 };
-use std::{fs, path::PathBuf};
+use regex::Regex;
 
 /// tokio-console dev tasks
 #[derive(Debug, clap::Parser)]
@@ -16,6 +23,9 @@ struct Args {
 enum Command {
     /// Generate `console-api` protobuf bindings.
     GenProto,
+
+    /// Check images needed for tokio-console docs.rs main page
+    CheckDocsImages,
 }
 
 fn main() -> Result<()> {
@@ -27,6 +37,7 @@ impl Command {
     fn run(&self) -> Result<()> {
         match self {
             Self::GenProto => gen_proto(),
+            Self::CheckDocsImages => check_docs_rs_images(),
         }
     }
 }
@@ -78,3 +89,71 @@ fn gen_proto() -> Result<()> {
         .compile_protos(&proto_files[..], &[proto_dir])
         .context("failed to compile protobuf files")
 }
+
+fn check_docs_rs_images() -> Result<()> {
+    eprintln!("checking images for tokio-console docs.rs page...");
+
+    let base_dir = {
+        let mut mydir = PathBuf::from(std::env!("CARGO_MANIFEST_DIR"));
+        ensure!(mydir.pop(), "manifest path should not be relative!");
+        mydir
+    };
+
+    let readme_path = base_dir.join("tokio-console/README.md");
+    let file =
+        fs::File::open(&readme_path).expect("couldn't open tokio-console README.md for reading");
+
+    let regex_line = line!() + 1;
+    let re = Regex::new(
+        r"https://raw.githubusercontent.com/tokio-rs/console/main/(assets/tokio-console-[\d\.]+\/\w+\.png)",
+    )
+    .expect("couldn't compile regex");
+    let reader = BufReader::new(file);
+    let mut readme_images = Vec::new();
+    for line in reader.lines() {
+        let Ok(line) = line else {
+            break;
+        };
+
+        let Some(image_match) = re.captures(&line) else {
+            continue;
+        };
+
+        let image_path = image_match.get(1).unwrap().as_str();
+        readme_images.push(image_path.to_string());
+    }
+
+    if readme_images.is_empty() {
+        let regex_file = file!();
+        let readme_path = readme_path.to_string_lossy();
+        return Err(eyre!(
+            "No images found in tokio-console README.md!\n\n\
+            The README that was read is located at: {readme_path}\n\n\
+            This probably means that there is a problem with the regex defined at \
+            {regex_file}:{regex_line}."
+        ));
+    }
+
+    let mut missing = Vec::new();
+    for image_path in &readme_images {
+        if !Path::new(image_path).exists() {
+            missing.push(image_path.to_string());
+        }
+    }
+
+    if missing.is_empty() {
+        eprintln!(
+            "OK: verified existance of image files in README, count: {}",
+            readme_images.len()
+        );
+
+        Ok(())
+    } else {
+        let mut error_buffer = "Tokio console README images missing:\n".to_string();
+        for path in missing {
+            writeln!(&mut error_buffer, " - {path}")?;
+        }
+
+        Err(eyre!("{}", error_buffer))
+    }
+}