Announcing rusty-man, a command-line viewer for rustdoc documentation

rusty-man (crates.io, lib.rs, source code) is a command-line viewer for documentation generated by rustdoc. It parses the HTML output of rustdoc, searches for a given keyword and formats the documentation similar to a manpage.

Example output for std::io::Error
$ rusty-man std::io::Error
std                                     Struct std::io::Error                              rusty-man

SYNOPSIS
      pub struct Error { /* fields omitted */ }

DESCRIPTION
      The error type for I/O operations of the `Read`, `Write`, `Seek`, and associated traits.

      Errors mostly originate from the underlying OS, but custom instances of `Error` can be created
      with crafted error messages and a particular value of `ErrorKind`.

METHODS
   impl Error
      new
            `pub fn new<E>(kind: ErrorKind, error: E) -> Error where
            E: Into<Box<dyn Error + Send + Sync>>, `

            Creates a new I/O error from a known kind of error as well as an arbitrary error
            payload.

            This function is used to generically create I/O errors which do not originate from the
            OS itself. The `error` argument is an arbitrary payload which will be contained in this
            `Error`.

            # Examples

            use std::io::{Error, ErrorKind};
            // errors can be created from strings
            let custom_error = Error::new(ErrorKind::Other, "oh no!");
            // errors can also be created from other errors
            let custom_error2 = Error::new(ErrorKind::Interrupted, custom_error);Run

[snip]

rusty-man can also read the generated search index, so you don’t even have to type the full name. If there are multiple matches, you can select one.

Displaying multiple matches
$ rusty-man Error
Found mulitple matches for Error – select one of:

[  0 ] alloc::fmt::Error: The error type which is returned from formatting a message…
[  1 ] anyhow::Error: The `Error` type, a wrapper around a dynamic error type.
[  2 ] clap::Error: Command Line Argument Parser Error
[  3 ] core::fmt::Error: The error type which is returned from formatting a message…
[  4 ] getrandom::Error: A small and `no_std` compatible error type.
[  5 ] gimli::read::Error: An error that occurred when parsing.
[  6 ] log::Level::Error: The \"error\" level.
[  7 ] log::LevelFilter::Error: Corresponds to the `Error` log level.
[  8 ] object::read::Error: The error type used within the read module.
[  9 ] proc_macro::Level::Error: An error.
[ 10 ] proc_macro_error::Level::Error
[ 11 ] rand::Error: Error type of random number generators
[ 12 ] rand_core::Error: Error type of random number generators
[ 13 ] serde::de::Error: The `Error` trait allows `Deserialize` implementations to…
[ 14 ] serde::de::value::Error: A minimal representation of all possible errors that can…
[ 15 ] serde::ser::Error: Trait used by `Serialize` implementations to generically…
[ 16 ] serde_json::Error: This type represents all possible errors that can occur…
[ 17 ] serde_json::error::Error: This type represents all possible errors that can occur…
[ 18 ] std::error::Error: `Error` is a trait representing the basic expectations for…
[ 19 ] std::fmt::Error: The error type which is returned from formatting a message…
[ 20 ] std::io::Error: The error type for I/O operations of the [`Read`],…
[ 21 ] syn::Error: Error returned when a Syn parser cannot parse the input…
[ 22 ] syn::parse::Error: Error returned when a Syn parser cannot parse the input…

> 20

Per default, rusty-man loads the documentation from the ./target/doc directory within the current working directory. It also searches the system documentation paths, i. e. /usr/share/doc/rust{,-doc}/html. You can specifiy additional search paths using the -s/--source option.

Limitations

  • As rusty-man parses the HTML output generated by rustdoc, it may not work with future Rust versions that change the output format.

Planned Improvements

  • Adding the documentation installed by rustup to the default search paths.
  • Adding a terminal user interface for better and faster navigation (following links, browsing history, jumping to a member, ...).
  • Loading documentation from a remote source, e. g. docs.rs or doc.rust-lang.org.

Please let me know if you have more suggestions or if you want to contribute to rusty-man!

Alternatives

  • cargo doc --open opens the generated documentation in a web browser.
  • oxidoc is a Rust documentation viewer that parses the Rust code to extract the documentation. Unfortunately, it no longer works with newer Rust versions and is unmaintained (issue).
11 Likes

This is fantastic -- thank you! :heart: