Any consensus on including long-form documentation in a crate?

help
1

I'd like to include some separate long-form documentation (in Markdown format) in a crate I'm developing. Ideally the source-code documentation could contain links to the long-form documentation residing in a top-level doc directory.

Until this kind of thing is officially supported, is there any community consensus on how to go about this?

I notice there are relevant RFC's and discussions:

https://github.com/steveklabnik/rustdoc/issues/24

https://github.com/rust-lang/cargo/issues/739

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

And the nom crate author has developed a tool for doing this:

https://github.com/Geal/cargo-external-doc

https://github.com/Geal/nom/tree/master/doc

Any advice or examples much appreciated,

Stu

2

I haven't kept up to date with the community consensus (or where things are headed), but I just created a couple of sub-modules and wrote my documentation there. See the cookbook and tutorial sub-modules in the csv crate for instance: csv - Rust

3

ructe also hacks this with modules: ructe::How_to_use_ructe - Rust

4

For now, IMHO, use mdbook, and publish to github pages.