Hacker News Reader

Comment by ashton314 | Hacker News Reader

I love the changes to the `rustup doc` command.

I first learned to program in Perl on a FreeBSD machine. (No GUI, mind you.) I had no way of browsing the internet, so my only source of documentation was via `perldoc`. Perl's documentation was so good I didn't ever need to go online.

Now, every time I encounter a new language, one of my favorite things is seeing the documentation available off-line, accessible via the command line. (Either directly from the terminal or opened in a browser.)

I've loved seeing the Rust community take documentation and error messages so seriously. It's nice to see this level of care.

View on HN

I came up and added that functionality. I spent many years as a UNIX sysadmin, everything was a `man` page away, including C libraries. I've done a lot of python over the past 7 years and used `pydoc` constantly. The inspiration for this came from `pydoc`, I wanted to replicate specifically the ability to lookup a specific call on a library such as `pydoc file.readlines`, hence the ability to do `rustup doc std::fs::read_dir`.

The funny thing is that I am fairly junior at Rust, and started using that functionality early on when I was trying to implement it, and really missed it every time I broke it or had to re-installed the prod version of rustup!

This is said a lot, but the Rust community is truly welcoming and helpful, even as a newcomer to Rust I got a lot of help and guidance on this. If you have an idea for a new functionality or fix something, don't let your inexperience stop you, go on discord and discuss it, write a small proof of concept and do a PR asking for feedback.

Two other things I discovered while working on this, which I find are not advertised enough (I added a mention about them to the RustBridge material):

• You can bring up a specific book with `rustup doc --book`, `rustup doc --embedded-book`, `rustup doc --nomicon` etc... (use `rustup doc -h` to see the list). Yes works offline too.

• It should obvious because it's right there, but I somehow totally missed it, and so did the few people I mentioneded it to since: There is either a search box or a symbol on every single `rustup doc` pages. It works really well and typically allow to find what you're looking for quickly. And yes, it too works offline!

Wow, this is great! It's nice to see this in a new/contemporary tool. I've caught myself mulling over taking a week at our cottage, working on some hobby project - only to realize that most of my "whe I find the time" To-do-list is crowded by various spa web stack stuff that I just know won't have an easy path to "pack what you need for a week of off line exploration" (when you don't already know enough what you'll need to look up, before you go offline to work..).

But now I can shift "do some stuff with Rust" higher up on that list, so thank you!

Ed: now the bad thing about lean core - fat ecosystem - and the great cargo - is of course that I will need to either "pack my expected dependencies", or just stick to the core... Which is great for learning, but kind of annoying if the plan isn't to write a database and a graphics library... But rather some kid of application. But we can't have everything.

Apart from the awesomeness that is `rustup doc`, check out `Zeal` https://zealdocs.org/.

It lets you download offline doc "packs" and search through them quickly.

This is inspired by Dash: https://kapeli.com/dash.

Is it inspired or a direct port? And are all doc sets supported? I have to admit that I use Dash way to often even though it’s just a glorified man page reader :) But I do miss it on windows and Linux.

It doesn't seem like a direct port, but it does use all the doc sets provided by Dash.

That doesn't seem too useful for Rust, where you can just run `cargo doc` to build a doc site covering your exact dependencies.

That was one thing I liked about Go as well. I mention Go cause I remember how I felt when I realized I had all the docs available offline. That is a nice to have for Rust too. I wonder when if ever LangServ will support code documentation as part of autocomplete like C# does rather cleanly with Visual Studio. Or is that already the case? In any case I think its powerful to be able to see a summary of a method through the auto complete feature of editors.

I know Rust is working on their own LangServ as well. I hope LangServ matures enough to secretly turn supporting editors into lightweight IDEs.

The Rust Language Server definitely serves up documentation beside each item in the completion menu, however it seems to be the raw Markdown source for the documentation, rather than the nicely formatted version you'd see in a browser.

At least in VS Code it's formatted nicely (at least most of the time, there are some ugly edge cases). Might depend on your editor integration though.

With the rust language server if you hover over a symbol you will see the same documentation as what’s available online. I use it daily.

Whaaaat are all the godocs available offline? Can I access this via the terminal?

That's amazing

Yes you can! It's one of the first times I even thought about offline docs that are rendered like that:

  godoc -http=:6060

Will do it for you. Then just visit localhost:6060

The current problem though is that it requires all your code + all the dependencies to be under $GOPATH/src. https://github.com/golang/go/issues/33655 starts with: "At this time, the godoc command is only able to display packages that are located in a GOPATH workspace."

If you use the Mac, you might like the app Dash.

Reply on news.ycombinator.com