roc -- cli rust documentation that rocks
----------------------------------------
[![Build](https://github.com/sminez/roc/workflows/Build/badge.svg?branch=master)](https://github.com/sminez/roc/actions?query=workflow%3ABuild)

`go doc` style command line searching through documentation for rust crates.

`roc` piggybacks off of the HTML documentation generated by rustdoc, so you will
need to run `cargo doc` before using roc if you want to look at anything other
that the standard library. `roc` only aims to provide a quick interface to track
down documentation summaries: most top level details will be shown but you
should pass the `-o` flag to your query if you need to read the full
documentation. This will open the local doc page using your default web browser.

### Some caveats
* This is very much a work in progress! There are multiple features that need
  implementing (grepping for partial matches, bash/zsh completion scripts,
  hoogle style searching by signature etc) and several known bugs, mostly in
  output formatting. If you have a use case that is not currenly covered or a
  ideas for functionality that could be added, please raise an issue on the
  GitHub repo or a PR if you are happy to implement the features yourself.
* `roc` assumes that you are using rustup and that you have stdlib docs downloaded.
  If not, you will be unable to search the docs of anything in `std`.
* `roc` requires that you build any dependency crate docs before they can be found.
  The simplest workflow is to run `cargo doc` whenever you update your
  `Cargo.toml` in order to ensure that your local generated docs are up to date.

### Example usage
```bash
# show summary comment for the Eq trait from stdlib
$ roc std::cmp::Eq
Trait for equality comparisons which are equivalence relations.

This means, that in addition to a == b and a != b being strict inverses, the equality must
be (for all a, b and c)


# generate the documentation for roc itself
$ cd roc && cargo doc


# list out all of the known crates that we can find from this directory
$ roc .
:: known crates
atty                  bit_set               bit_vec               bitflags              cfg_if
clap                  clap_derive           colored               debug_unreachable     futf
heck                  html5ever             implementors          indexmap              lazy_static
libc                  log                   mac                   markup5ever           markup5ever_rcdom
os_str_bytes          phf                   phf_shared            precomputed_hash      proc_macro2
proc_macro_error      proc_macro_error_attr quote                 rocdoc                select
serde                 siphasher             std                   string_cache          strsim
syn                   syn_mid               tendril               term_size             termcolor
textwrap              time                  unicode_segmentation  unicode_width         unicode_xid
utf8                  vec_map               xml5ever


# show top level summary details for the roc crate
$ roc rocdoc
roc - command line doucmentation that rocks

roc is an attempt at bringing godoc style quick docs searching to the command
line for rust. It doesn\'t generate any documentation itself, instead it relies
entirely on the local HTML output created by running cargo doc in the root of
your crate. You will need to have rust installed via rustup and have the std lib
docs downloaded in order to look at std lib.

:: modules
locate  Locate the generated docs that we have available within the current workspace
parse   Parse the contents of rustdoc generated HTML files
pprint  Formatted output and pretty printing


# show specific information about the Locator struct
$ roc rocdoc::locate::Locator
pub struct Locator { /* fields omitted */ }

A Locator handles mapping a user query string from the command line to a file
location on disk. It also provides information about what kind of documentation
file it has found so that the appropriate parsing of the file contents can be
carried out.

pub fn new(query: String) -> Self
pub fn target_file_path(&self) -> Option<String>
pub fn determine_tagged_path(&self) -> Option<TaggedPath>
```

### Curent flags
```
-l, --list   list out modules under the current path
-o, --open   open the selected doc page in the browser (local copy)
```

### Local file system doc locations
```
std::* -> $(rustc --print sysroot)/share/doc/rust/html/std
*      -> $(dirname Cargo.toml)/target/doc
```