Include Readme.md in rustdoc?


#1

Is it possible to include the Readme.md of a github project as the the top-level library documentation in rustdoc?
Github readme files often include a description and example code for the project and in my case I also would like to include this content in the documentation generated by rustdoc without duplication.

Is there already a stable way to do this? Or would I need my own proc_macro, e.g., as done in the Unstable Book with the panics example?


#2

Unfortunately, I don’t know the direct answer to your question. At the moment, I don’t know how to use READMEs that way. However, @steveklabnik recently announced that he’s working on a rewrite of rustdoc, and this may be a great opportunity to add your thoughts into the conversation.


#3

There is not currently a stable way to do this, but @mgattozzi has RFC 1990 in the works that would enable this!


#4

Thanks for the information, this will be a useful feature. I’ll continue to copy/paste for the time being :wink:


#5

If you do want the feature and have some ideas please drop by the RFC and leave some comments as well. It’d be good to get some other perspectives :smiley:


#6

Maybe not what you ask, but there is cargo-readme


Which solves your duplication problem. The only caveat is that: now you have to write the document inside the library as comment.


#7

@ivanceras thanks for the tip, that would be an option as long as the cargo extension is run regularly. Maybe it’s possible to automatically run this on cargo build or pre-cargo package, e.g., via make or as part of the crate’s build.rs.

@mgattozzi I’ll have a closer look at the RFC. Maybe I can contribute something that is missing.