Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sminez/roc

Rust command line documentation searching
https://github.com/sminez/roc

command-line command-line-tool documentation rust

Last synced: 13 days ago
JSON representation

Rust command line documentation searching

Awesome Lists containing this project

README 

        
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

pub fn determine_tagged_path(&self) -> Option

```



### 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

```