<!---
SPDX-FileCopyrightText: 2020 Robin Krahl <robin.krahl@ireas.org>
SPDX-License-Identifier: MIT
-->

# rusty-man

```
$ rusty-man rusty-man | head -4
rusty-man                                 Module rusty-man                                 rusty-man

DESCRIPTION
      rusty-man is a command-line viewer for documentation generated by `rustdoc`.
```

## Example Usage

Before running rusty-man, make sure that you generated the documentation with
`cargo doc`:
```
$ cd rusty-man && cargo doc
```

Then you can open the documentation for an item:
```
$ rusty-man kuchiki::NodeRef
```

You don’t have to specificy the full item name:
```
$ rusty-man NodeRef
```

If the documentation is not placed in `./target/doc` or
`/usr/share/doc/rust{,-doc}/html`, you have to manually set the source path
using the `-s`/`--source` option:
```
$ rusty-man --source ~/.rustup/toolchains/stable-*/share/doc/html io::Error
```

If there are multiple matches for the keyword, rusty-man will show you a list
of all matching items:
```
$ rusty-man --source ~/.rustup/toolchains/stable-*/share/doc/rust/html u8
Found mulitple matches for u8 – select one of:

[ 0 ] core::u8: The 8-bit unsigned integer type.
[ 1 ] std::u8: The 8-bit unsigned integer type.

> 1
```

For more usage information, run `rusty-man --help`.

## Installation

To install rusty-man, clone this repository and use cargo to build the project.
See the [`INSTALL.md`](./INSTALL.md) file for more information.

rusty-man should run on all platforms supported by [`termion`][].  If you have
trouble running rusty-man on your platform or if you want to help porting
rusty-man to other platforms, please let me know.

## Contributing

Contributions to this project are very welcome!  You can contribute by writing
code or documentation or by testing.  See the [`CONTRIBUTING.md`][] file for
more information.

If you are looking for a good starting point, have a look at the [issues with
the label “good first issue”][issues] in rusty-man’s issue tracker.

## Minimum Supported Rust Version

This crate supports Rust 1.40 or later.

## Contact

For bug reports, patches, feature requests or other messages, please send a
mail to the mailing list [~ireas/rusty-man-dev@lists.sr.ht][] ([public
archive][]) or [contact me directly][].  You can also use the rusty-man [issue
tracker][] for bug reports or features requests.

## License

This project is licensed under the [MIT License][].

`rusty-man` complies with [version 3.0 of the REUSE specification][reuse].

[`termion`]: https://lib.rs/termion
[`CONTRIBUTING.md`]: ./CONTRIBUTING.md
[issues]: https://todo.sr.ht/~ireas/rusty-man?search=label:%22good%20first%20issue%22%20status%3Aopen
[~ireas/rusty-man-dev@lists.sr.ht]: mailto:~ireas/rusty-man-dev@lists.sr.ht
[contact me directly]: mailto:robin.krahl@ireas.org
[public archive]: https://lists.sr.ht/~ireas/rusty-man-dev
[issue tracker]: https://todo.sr.ht/~ireas/rusty-man
[MIT license]: https://opensource.org/licenses/MIT
[reuse]: https://reuse.software/practices/3.0/