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

#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:

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

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: https://docs.rs/csv/1.0.0/csv/

#3

ructe also hacks this with modules: https://docs.rs/ructe/0.3.16/ructe/How_to_use_ructe/index.html

#4

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