How is it possible to keep Rust module documentation in separate Markdown files?

Question

This section of the Rust book seems to imply that it is possible to keep Rust documentation in separate .md files, but it does not say how these .md files can then be included back. How does this work?

Millikan

Answer 1

It doesn't. That section on describing the functionality of rustdoc is saying that it can process individual .md files. The third paragraph touches on this:

Documentation can be generated in two ways: from source code, and from standalone Markdown files.

Insofar as I am aware, there is no extant way to put code documentation in external files. It would be theoretically possible to do so using a procedural derive macro, but I'm not aware of any crate that actually does this.

Twobyfour

Thanks. I didn't think that paragraph made it clear, but it is what it is. – Millikan

**squints and turns head** Yeah, I can kinda see how you could read that as supporting external files, especially if you went in expecting that feature. With that in mind, I'm not sure what would avoid the confusion short of an explicit "this isn't supported" disclaimer. – Twobyfour

So in other words, these .md files would only be useful for general-purpose documentation about the crate and not specifically tied to any part of the crate? – Selfdenial

@BHustus: Standalone .md files are just that: standalone. They don't have anything to do with any crate. You can use them to write blog posts if you want; rustdoc doesn't really care. – Twobyfour

Answer 2

The syntax for putting Rust module documentation in separate Markdown files is:

#![doc = include_str!("path/to/some-documentation.md")]

/* content of the module */

This is supported since stable Rust 1.54.0.

On old nightly compilers from 1.50.0-nightly through 1.53.0-nightly, an unstable feature is required in order for the above to be available.

#![feature(extended_key_value_attributes)]

#![doc = include_str!("path/to/some-documentation.md")]

On nightly compilers 1.24.0-nightly through 1.53.0-nightly, the following alternative syntax is available, but has since been removed.

#![feature(external_doc)]

#![doc(include = "path/to/some-documentation.md")]

Bernhardt

The frustrating thing being, of course, that it's hard to recommend unstable features when they might change or go away at any time. – Twobyfour

On the flip side, people need to use unstable features and provide feedback about them before anything can be stabilized. Without anybody using features they would just sit in nightly forever or be scrapped. – Bernhardt

Answer 3

In stable Rust, you can mimic the unstable external-doc feature through clever macros.

An easy way to do this is to use the doc-comment crate:

#[macro_use]
extern crate doc_comment;

// If you want to test examples in your README file.
doctest!("../README.md");

// If you want to document an item:
doc_comment!(include_str!("another_file.md"), pub struct Foo {});

You can see a complicated version of this in my crate SNAFU, where I use it for the user's guide.

The "by-hand" version involves passing the thing to be documented along with the included markdown:

macro_rules! inner {
    ($text:expr, $($rest: tt)*) => {
        #[doc = $text]
        $($rest)*
    };
}

inner! {
    include_str!("/etc/hosts"),
    mod dummy {}
}

See also:

• Is it possible to emit Rust attributes from within macros?
• How to embed a Rust macro variable into documentation?
• Generating documentation in macros

Introjection