New cargo subcommand: sync-readme

New cargo subcommand: sync-readme

cargo, subcommand, readme

2019-02-25 18:50:00 UTC, by Dimitri Sabadie


Have you ever struggled with welcoming people on your project pages, be them on GitHub or docs.rs? One major problem we’re facing when developping crates is that we need to maintain several places where documentation is important:

However, sometimes, I just don’t want to bother writing twice the same thing and honestly, I don’t really know whether the README file is a good place to write an onboarding section, since that should also be included in your Rust documentation on docs.rs.

So… I’ve been thinking of a way to fix that, without really investing too much time in it. But lately, I came to the realization that I often have this pattern:

  1. Write the onboarding documentation in my lib.rs or main.rs. For instance, I’m pretty proud of the onboarding documentation of warmy. It’s exhaustive, easy for newcomers, it has plenty of links and explanations and it renders pretty nice on docs.rs.
  2. Write a header in the README file with badges etc. and then copy the Rust onboarding documentation in the readme.

Here, (2.) is a manual and annoying task: I open my editor, make a block selection of the documentation, store it in a buffer, apply a smart macro on it to remove the Rust annotation and then paste the result in the README after having purged it from the previous documentation… That’s tedious and not very interesting.

cargo sync-readme to the rescue!

So, yesterday, I decided to start working on a small tool that would automate all this for me. The idea is the following:

This is really all you have to do. cargo sync-readme will take care of the rest for you. There’re two hypothesis that the command requires to be true, though:

Basically, insert the marker once, and run cargo sync-readme. Every time you change your Rust documentation, just call cargo sync-readme once again to synchronize the documentation in your README file.

On workspace crates

Currently, cargo sync-readme doesn’t work with workspace crates. You will have to go into each of the workspace’s members to run cargo sync-readme if you want to synchronize their respective READMEs.

Conclusion

cargo sync-readme is already available on crates.io for you to use. You can install it as a development tool with the following command:

cargo install cargo-sync-readme

Disclaimer: after having published cargo-sync-readme, I was told that there is already another cargo plugin, cargo-readme, that already does that. Indeed, that crate does more or less the same job. However, the way it does it is very different. First, it uses a template file while cargo-sync-readme lets you use your README file without having to depend on a template. Also, cargo-readme has special semantics in its template (like {{crate_name}}, etc.) while cargo-sync-readme is simpler and just requires a single marker. To sum up: cargo-readme is heavier and is likely to require you to break your file into two separate files but contains more customization options while cargo-sync-readme only requires a single line in your README and will synchronize from within that same file.

Feel free to comment, open issues, drink beers, share that awesome bear driving a sausage podracer and most of all… keep the vibes!