rust-lang / rust-lang/rfcs

`cargo doc` optionally includes stdlib from `rustup`

Open
#2,324 9 comments 73 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

T-cargo T-doc
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.