Readme

The purpose of a README is for people to get a very brief introduction to what you project does. For open-source projects it is essential, when people decide if your crate solves the issue they are trying to solve. It does not need to be a comprehensive documentation document, rather a very dense summary that contains some vital pieces of information of what your crate does, how it compares to other crates that achieve similar goals, and what limitations it has.

There are some common patterns that make for useful README files, and this chapter will attempt to illustrate them.

Badges

Badges are little images that you can embed into your README that show up-to-date information on your Rust project. These are useful because they do not need need to be updated manually.

Generally, you can put them on your README like this:

# Project Name

[![crates.io version](https://img.shields.io/crates/v/imstr.svg)](https://crates.io/crates/imstr)
[![docs.rs documentation](https://img.shields.io/docsrs/imstr)](https://docs.rs/imstr)

Common badges for Rust crates

These badges pull information on crates published on crates.io. By definition, these will not pull data from source control, but rather from whatever is published. They render information such as the most recent version, status of automatically built documentation, download counts, and health checks for dependencies.

Crate:

Badge	Markdown

Generating a readme file from crate-level documentation

The Readme section shows some tools that you can use to generate a README file from crate-level documentation.