Tracking issue: rfc 1990 - add external doc attribute to rustc

[nrc]

RFC PR: rust-lang/rfcs#1990
RFC text: https://github.com/rust-lang/rfcs/blob/master/text/1990-external-doc-attribute.md

Current documentation

---

Summary of how to use this:

1. Add #![feature(external_doc)] to your crate.
2. Add a file "src/some-docs.md" with some docs to your crate.
3. Add an attribute #[doc(include = "some-docs.md")] to something that needs some docs. The file path is relative to lib.rs, so if you want a doc folder to live alongside src, then all your paths inside the doc(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

[matklad]

cc @joshtriplett

At today's Cargo meeting, and interesting question was raised how Cargo should check if it should rebuild the docs when an external file with docs changes.

Here's some info on how dependency-tracking works today:

When doing cargo build, Cargo passes an --emit=deb-info flag to rustc, which causes it to emit dep-info files with .d extension, which lists what files were used for compilation (remember, only crate roots are explicitly mentioned in Cargo.toml). These files then used in fingerprint.rs to compute the fingerprint.

Curiously, cargo doc does not emit dep-info at all, and fingerpint.rs does not use depinfo when doing doc. Instead it asks Source for fingerprint which for the local repository boils down to listing all files in a directory with Cargo.toml.

TL;DR: touch Readme.md today causes cargo doc to rebuild docs for the current crate, which might not be the most efficient thing to do, but which should work with external documentation, unless it is fetched from a place outside of Cargo package.

[joshtriplett]

@matklad So, it sounds like the current behavior is correct but could be made more efficient. That's better than being incorrect.

[matklad]

So, it sounds like the current behavior is correct but could be made more efficient.

There's an edge case where it might not do rebuild when it should, if in src/lib.rs you have something like

#[path="../../bar.rs"]
pub mod bar;

Or

include!("../../bar.rs")

That is, if you touch files outside of the Cargo package directory.

Other than that yes, current behavior is correct!.