-
Notifications
You must be signed in to change notification settings - Fork 13.6k
Closed
Labels
A-attributesArea: Attributes (`#[…]`, `#![…]`)Area: Attributes (`#[…]`, `#![…]`)B-unstableBlocker: Implemented in the nightly compiler and unstable.Blocker: Implemented in the nightly compiler and unstable.C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCCategory: An issue tracking the progress of sth. like the implementation of an RFCF-external_doc`#![feature(external_doc)]``#![feature(external_doc)]`P-mediumMedium priorityMedium priorityT-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.Relevant to the dev-tools subteam, which will review and decide on the PR/issue.T-langRelevant to the language teamRelevant to the language teamT-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.Relevant to the rustdoc team, which will review and decide on the PR/issue.
Description
RFC PR: rust-lang/rfcs#1990
RFC text: https://github.com/rust-lang/rfcs/blob/master/text/1990-external-doc-attribute.md
Summary of how to use this:
- Add
#![feature(external_doc)]
to your crate. - Add a file
"src/some-docs.md"
with some docs to your crate. - Add an attribute
#[doc(include = "some-docs.md")]
to something that needs some docs. The file path is relative tolib.rs
, so if you want adoc
folder to live alongsidesrc
, then all your paths inside thedoc(include)
attributes need to begin with../doc
.
Summary of current status:
- Initial implementation landed in rustdoc: include external files in documentation (RFC 1990) #44781, on 2017-11-22.
- Updates based on conversation in this thread landed in tweaks and fixes for doc(include) #46858, on 2017-12-21.
- Please use this in your own projects and comment in this thread if something goes wrong! (Or even if it goes well! Knowing it's working as intended is great!)
Current tasks:
- Land rustdoc: include external files in documentation (RFC 1990) #44781
-
(promote the "failed to load file" warnings to proper lints?)(Make them hard errors instead, per the RFC tweaks and fixes for doc(include) #46858) - Ensure line number info is properly preserved in doctest errors
kornelski, MatthieuBizien, LPGhatguy, ozkriff, jonas-schievink and 26 more
Metadata
Metadata
Assignees
Labels
A-attributesArea: Attributes (`#[…]`, `#![…]`)Area: Attributes (`#[…]`, `#![…]`)B-unstableBlocker: Implemented in the nightly compiler and unstable.Blocker: Implemented in the nightly compiler and unstable.C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCCategory: An issue tracking the progress of sth. like the implementation of an RFCF-external_doc`#![feature(external_doc)]``#![feature(external_doc)]`P-mediumMedium priorityMedium priorityT-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.Relevant to the dev-tools subteam, which will review and decide on the PR/issue.T-langRelevant to the language teamRelevant to the language teamT-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.Relevant to the rustdoc team, which will review and decide on the PR/issue.