`rustup doc` should support searching for names

[joshtriplett]

Problem you are trying to solve

rustup doc requires giving the exact path to an item in order to get its documentation. I'd love to write rustup doc File rather than rustup doc std::fs::File.

Solution you'd like

rustup doc File should open the documentation for std::fs::File.

This could work by doing the search in rustup, or by opening the rustdoc search page with a query of File.

Notes

No response

[rami3l]

@joshtriplett Thanks for your feedback!

I do think we can always inject ?search=<query> at the end of the URL assuming the page is almost always mdbook or rustdoc-based. #4070 should have provided necessary groundwork for this feature...

There's one caveat though: since the positional argument already has a meaning (path navigation), we should come up with a new syntax. Do you happen to have any proposal in mind? rustup doc --search=File or rustup doc -s=File might look a bit long...

[joshtriplett]

While it might make sense to have an argument to specify a query explicitly, what I'm looking for here is an automatic guessing of whether something needs a search. rustup doc File, for instance, currently says "error: No document for 'File'". I'm suggesting that rather than erroring it could search for something that matches (std::fs::File) and open that.

[ChrisDenton]

How would it know which document to search for File? Or would it always just assume std? Or would it search all docs. But then how?

[joshtriplett]

Ideally, it does a search of std internally (rather than just forwarding the query), so that it knows there's a result to open. If an argument would otherwise error, and a search of std would produce some results, opening the search seems better than an error.

[rami3l]

How would it know which document to search for File? Or would it always just assume std? Or would it search all docs. But then how?

@ChrisDenton That's not a problem since we focus on one book each time. Without any flags it'll be std, with flags for a specific book it'll be that book.

[ChrisDenton]

Ok, I think that'd work then? If the argument to rustup doc is a single item (i.e. no :: or /, etc) then search the file system if it fails otherwise.

So: if the user types File then search doc_root/std/**/*.File.html?

EDIT: where the * in *.File.html means one of fn, trait, etc

[rami3l]

So: if the user types File then search doc_root/std/**/*.File.html?

@ChrisDenton I still doubt whether we should do a FS-level search by ourselves since having to search in a range of 20K small text files (well, not all at once, but still quite a lot I think) might cause performance issues real quick... And sometimes a path component would mean a page, sometimes an anchor within a page. Forwarding to mdbook or rustdoc means we'll have the best of both worlds for free.

[ChrisDenton]

Hmm... does it need to be anything more than a simple file name check? That would be fast enough. True, it would be limited to finding top-level items but that seems like an acceptable trade-off and not mutually exclusive with having a full search command?

[rami3l]

@ChrisDenton #4069 asks for the broken_intra_doc_links anchor in --rustdoc, and currently that would be rustup doc --rustdoc lints::broken_intra_doc_links. If, like you've said, for the positional arg it's limited to file names, then that looks okay, but what about fuzzy matches in that case?

[ChrisDenton]

I think having --search (or -s for short) for fuzzy matches would be ok? The "no document" error message can then mention it as an alternative.

That would be easy enough to explain I feel. A positional argument searches for a "topic" (i.e. for a particular page) whereas --search opens the mdbook search page.

[joshtriplett]

@ChrisDenton That would mean users have to know that they can't search for a method name. It's still an improvement over the status quo, though.