Merge rust-bitcoin/rust-bitcoin-maintainer-tools#107: cargo-rbmt: clean docs and extend with --open arg

e35355f cargo-rbmt: beef up the api's implicit dep requirement docs (Nick Johnson)
91491fb cargo-rbmt: extend docs with the often use --open arg (Nick Johnson)
50667c9 cargo-rbmt: simplify justfile (Nick Johnson)

Pull request description:

ACKs for top commit:
  tcharding:
    ACK e35355f

Tree-SHA512: 2ee85f42e4ea736195e9e62a5c0036353055cabd223b9b7b124d9f3e04285be67ab4031d9bfc6a798538d0e218a59d0b5f100aaa6a2590518422e8f20f165079

Author: tcharding

cargo-rbmt/README.md

@@ -151,7 +151,9 @@ When you specify `--lock-file`, the tool copies that lock file to `Cargo.lock` b
 
 ## API
 
-The `api` command helps maintain API stability by generating public API snapshots and checking for breaking changes. It uses the [public-api](https://github.com/Enselic/cargo-public-api) crate to analyze a crate's public interface. **Requires running with a nightly toolchain after nightly-2025-08-02** due to docsrs dependencies.
+The `api` command helps maintain API stability by generating public API snapshots and checking for breaking changes. It uses the [public-api](https://github.com/Enselic/cargo-public-api) crate to analyze a crate's public interface.
+
+> **NOTE:** `api` has an implicit dependency on the version of the nightly toolchain since it relies on an unstable docsrs interface. Currently, it requires [*nightly-2025-08-02* or later](https://github.com/cargo-public-api/cargo-public-api/blob/main/README.md#compatibility-matrix).
 
 ```bash
 cargo rbmt api

cargo-rbmt/justfile

@@ -1,37 +1,36 @@
-# This justfile is functional for cargo-rbmt, but also showcases a pattern for
-# how to integrate rbmt into a justfile.
-#
-# The generic `_rbmt` recipe handles lock file selection (existing, recent,
-# minimal) and installation of rbmt. Toolchain selection is handled internally
-# by rbmt.
-#
-# Specific recipes (`lint`, `test`) call the generic `_rbmt` recipe with
-# appropriate defaults.
+# This justfile is functional for cargo-rbmt, but also showcases
+# a pattern for how to integrate rbmt into a justfile.
 
 # List available recipes.
 _default:
     @just --list
 
 # Install rbmt from the local workspace path.
+[group('system')]
 @install:
     cargo install --quiet --path .
 
 # Install workspace toolchains.
+[group('system')]
 @toolchains: install
+    # Redirect exports since just recipes are a sub-shell.
     RBMT_LOG_LEVEL=quiet cargo rbmt toolchains > /dev/null
 
-# Run CI tasks using rbmt.
-@_rbmt task lock="existing": install toolchains
-    RBMT_LOG_LEVEL=quiet cargo rbmt --lock-file {{lock}} {{task}}
+# Setup rbmt and run with given args.
+@rbmt *args: toolchains
+  RBMT_LOG_LEVEL=quiet cargo rbmt {{args}}
+
+# Build and open docs.
+@docs: (rbmt "docsrs --open")
 
 # Format files.
-@fmt: (_rbmt "fmt")
+@fmt: (rbmt "fmt")
 
 # Lint with clippy.
-@lint: (_rbmt "lint")
+@lint: (rbmt "lint")
 
 # Run tests.
-@test: (_rbmt "test")
+@test: (rbmt "test")
 
 # Update Cargo-minimal.lock and Cargo-recent.lock files.
-@lock: (_rbmt "lock")
+@lock: (rbmt "lock")

cargo-rbmt/src/docs.rs

@@ -10,7 +10,7 @@ use crate::toolchain::{prepare_toolchain, Toolchain};
 ///
 /// This verifies that `cargo doc` works correctly for users with stable Rust.
 /// Uses basic rustdoc warnings to catch common documentation issues.
-pub fn run(sh: &Shell, packages: &[Package]) -> Result<(), Box<dyn std::error::Error>> {
+pub fn run(sh: &Shell, packages: &[Package], open: bool) -> Result<(), Box<dyn std::error::Error>> {
     prepare_toolchain(sh, Toolchain::Stable)?;
 
     let mut cmd = quiet_cmd!(sh, "cargo --locked doc --all-features --no-deps");
@@ -20,6 +20,10 @@ pub fn run(sh: &Shell, packages: &[Package]) -> Result<(), Box<dyn std::error::E
         cmd = cmd.args(&["-p", &package.id]);
     }
 
+    if open {
+        cmd = cmd.arg("--open");
+    }
+
     cmd.env("RUSTDOCFLAGS", "-D warnings").run()?;
 
     Ok(())
@@ -29,7 +33,11 @@ pub fn run(sh: &Shell, packages: &[Package]) -> Result<(), Box<dyn std::error::E
 ///
 /// This emulates the docs.rs build environment by using the nightly toolchain
 /// with `--cfg docsrs` enabled. This catches docs.rs-specific issues.
-pub fn run_docsrs(sh: &Shell, packages: &[Package]) -> Result<(), Box<dyn std::error::Error>> {
+pub fn run_docsrs(
+    sh: &Shell,
+    packages: &[Package],
+    open: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
     prepare_toolchain(sh, Toolchain::Nightly)?;
 
     let mut cmd = quiet_cmd!(sh, "cargo --locked doc --all-features --no-deps");
@@ -39,6 +47,10 @@ pub fn run_docsrs(sh: &Shell, packages: &[Package]) -> Result<(), Box<dyn std::e
         cmd = cmd.args(&["-p", &package.id]);
     }
 
+    if open {
+        cmd = cmd.arg("--open");
+    }
+
     cmd.env("RUSTDOCFLAGS", "--cfg docsrs -D warnings -D rustdoc::broken-intra-doc-links").run()?;
 
     Ok(())

cargo-rbmt/src/main.rs

@@ -54,9 +54,17 @@ enum Commands {
     /// Run the linter (clippy) for workspace and all crates.
     Lint,
     /// Build documentation with stable toolchain.
-    Docs,
+    Docs {
+        /// Open documentation in browser after building.
+        #[arg(long)]
+        open: bool,
+    },
     /// Build documentation with nightly toolchain for docs.rs.
-    Docsrs,
+    Docsrs {
+        /// Open documentation in browser after building.
+        #[arg(long)]
+        open: bool,
+    },
     /// Run benchmark tests for all crates.
     Bench,
     /// Run tests with specified toolchain.
@@ -164,13 +172,13 @@ fn main() {
                 eprintln!("Error running lint task: {}", e);
                 process::exit(1);
             },
-        Commands::Docs =>
-            if let Err(e) = docs::run(&sh, &packages) {
+        Commands::Docs { open } =>
+            if let Err(e) = docs::run(&sh, &packages, open) {
                 eprintln!("Error building docs: {}", e);
                 process::exit(1);
             },
-        Commands::Docsrs =>
-            if let Err(e) = docs::run_docsrs(&sh, &packages) {
+        Commands::Docsrs { open } =>
+            if let Err(e) = docs::run_docsrs(&sh, &packages, open) {
                 eprintln!("Error building docs.rs docs: {}", e);
                 process::exit(1);
             },