Cargo-readme: generate README.md from doc comments

announcements
1

This week I was working on cargo-readme, a cargo subcommand that generates README.md from your crate's doc comments.

It is almost done, but I still need some suggestions on it.

First, cargo-readme appends a '#' to headings on the doc comment (can be disabled with flag), for example '# heading' becomes '## heading' and so on, so the first heading may be your crate/project name. Is this behavior correct/desired? Can it give wrong results?

Second, the result can be generated by a template file (thanks to ogeon's suggestion). cargo-readme by default looks for a file called README.tpl and, if not found, just outputs the result. The template file can also be specified as an option. In the template, {{crate}} is replaced with the crate name extracted from Cargo.toml and {{docs}} with the result from the doc comments. Any suggestions on this?

Thank you for your comments and I hope cargo-readme could be useful to the rust community.

3 Likes
2

Cool! I'll be adding this to my growing pile of ~/bin/cargo-*!

This still duplicates the code, though. That's why I'd love to see it done the other way around: #![doc(include("Readme.md"))]. (This will require compiler/rustdoc support.)

3

I believe the other way around is trickier because README.md usually contains information not related with documentation, like badges, so you will have to somehow mark where the documentation starts and ends.

It's a really good idea, btw. Maybe I try to do it some day.