Skip to content

Commit 04e538c

Browse files
committed
1a: mention html_root_url for generated docs
1 parent 70ee253 commit 04e538c

File tree

1 file changed

+23
-0
lines changed

1 file changed

+23
-0
lines changed

text/0000-build-std/4-stage-1a.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -365,6 +365,19 @@ or workspace ([?][rationale-caching]).
365365

366366
- [*Why not globally cache builds of the standard library?*][rationale-caching]
367367

368+
## Generated documentation
369+
[generated-documentation]: #generated-documentation
370+
371+
When running `cargo doc` for a project to generate documentation and rebuilding
372+
the standard library, the generated documentation for the user's crates will
373+
link to the locally generated documentation for the `core`, `alloc` and `std`
374+
crates, rather than the upstream hosted generation as is typical for non-locally
375+
built standard libraries.
376+
377+
*See the following sections for rationale/alternatives:*
378+
379+
- [*Why not link to hosted standard library documentation in generated docs?*][rationale-generated-docs]
380+
368381
## Cargo subcommands
369382
[cargo-subcommands]: #cargo-subcommands
370383

@@ -860,6 +873,16 @@ the standard library.
860873

861874
[*Caching*][caching]
862875

876+
## Why not link to hosted standard library documentation in generated docs?
877+
[rationale-generated-docs]: #why-not-link-to-hosted-standard-library-documentation-in-generated-docs
878+
879+
Cargo would need to pass `-Zcrate-attr="doc(html_root_url=..)"` to the standard
880+
library crates when building them but doesn't have the required information to
881+
know what url to provide. Cargo would require knowledge of the current toolchain
882+
channel to build the correct url and doesn't know this.
883+
884+
[*Generated documentation*][generated-documentation]
885+
863886
# Unresolved questions
864887
[unresolved-questions]: #unresolved-questions
865888

0 commit comments

Comments
 (0)