`cargo doc` optionally includes stdlib from `rustup`
Nobody has claimed this yet.
- Dominant language
- Markdown
- Stars
- 6.6k
- Forks
- 1.7k
- Avg merge
- 16h 14m
- Merged PRs (30d)
- 1
Description
A typical set up when writing code is to add all one's dependencies to Cargo.toml and run cargo doc --open to pull up a browser window with all the relevant API docs in one place. But there is one big exception - it is missing the standard lib. For that one must run rustup doc --std which of course then opens in a separate tab (possibly in a different instance of the browser).
This is made doubly annoying by the fact that many crate docs link back to the standard libary, but when one clicks such a link it redirects to doc.rustlang.org rather then the local copy.
Proposal: optionally make cargo aware of local stdlib doc instances and hook them into the generated crate docs using the flag cargo doc --local-std (bikeshed-able). Then all docs would be accessible from one tab window and one can remain within this closed loop while browsing the docs. This would be especially useful for offline work.
Drawbacks:
This is arguably a bit of a hack since cargo is not supposed to be aware of rustup (although there are some proposals to eventually combine the two).
Possibly difficult to implement, since the current doc generation expects all static files to be in one parent folder. Not clear how e.g. search would work.
This feature is a little brittle and would fail if rustup docs cannot be found (or are in an unusual location). It should never be accidentally used for online doc hosting.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the proposal for cargo doc --local-std and its interaction with rustup doc --std. Investigate how generated crate documentation locates static files and how standard-library links and search would work across locations. Done means defining a viable optional integration that remains safe for online hosting and handles missing or unusual rustup docs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100