Rustup 1.20.0 (opens in new tab)

(blog.rust-lang.org)

217 pointspietroalbini6y ago20 comments

20 comments

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.

dorfsmay6y ago

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.

dorfsmay6y ago

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!

1 more reply

manaskarekar6y ago

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.

larusso6y ago

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.

1 more reply

Nullabillity6y ago

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

giancarlostoro6y ago

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.

thristian6y ago

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.

1 more reply

hazz996y ago

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

That's amazing

1 more reply

nitsky6y ago

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.

coldtea6y ago

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

benschulz6y ago

That updating the nightly toolchain gets more convenient is fantastic. It was oftentimes a struggle, especially when there was no build with all required components listed as present in the toolchain status history[1].

[1]: https://rust-lang.github.io/rustup-components-history/

skybrian6y ago

> Due to the large number of installed files

It sounds like the Rust distribution needs to use zip files more?

topspin6y ago

    $ rustup component list | grep installed
    cargo-x86_64-unknown-linux-gnu (installed)
    rust-docs-x86_64-unknown-linux-gnu (installed)
    rust-std-x86_64-unknown-linux-gnu (installed)
    rustc-x86_64-unknown-linux-gnu (installed)
    rustfmt-x86_64-unknown-linux-gnu (installed)
    $ find ~/.cargo -type f | wc -l
    8699

8K files... So 1 to 2 orders of magnitude less than any given frontend node_modules folder. Pretty reasonable actually.

steveklabnik6y ago

A big part of that is rust-docs; each page is its own file, so that you don't need a web server.

j / k navigate · click thread line to collapse

20 comments

ashton3146y ago

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

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

dorfsmay6y ago

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.

1 more reply

manaskarekar6y ago

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.

larusso6y ago

1 more reply

Nullabillity6y ago

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

giancarlostoro6y ago

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

thristian6y ago

1 more reply

hazz996y ago

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

That's amazing

1 more reply

nitsky6y ago

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.

coldtea6y ago

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

benschulz6y ago

[1]: https://rust-lang.github.io/rustup-components-history/

skybrian6y ago

> Due to the large number of installed files

It sounds like the Rust distribution needs to use zip files more?

topspin6y ago

    $ rustup component list | grep installed
    cargo-x86_64-unknown-linux-gnu (installed)
    rust-docs-x86_64-unknown-linux-gnu (installed)
    rust-std-x86_64-unknown-linux-gnu (installed)
    rustc-x86_64-unknown-linux-gnu (installed)
    rustfmt-x86_64-unknown-linux-gnu (installed)
    $ find ~/.cargo -type f | wc -l
    8699

8K files... So 1 to 2 orders of magnitude less than any given frontend node_modules folder. Pretty reasonable actually.

steveklabnik6y ago

A big part of that is rust-docs; each page is its own file, so that you don't need a web server.

j / k navigate · click thread line to collapse