cargo-doc2readme

cargo doc2readme is a cargo subcommand to create a readme file to display on Codeberg, GitHub or crates.io, containing the rustdoc comments from your code.

Installation

AlpineLinux

On AlpineLinux 3.23 and newer, you can install cargo-doc2readme using apk:

apk add cargo-doc2readme

ArchLinux

If you are using ArchLinux, you can install cargo-doc2readme from the AUR:

yay -S cargo-doc2readme

Other

On other Operating Systems, make sure you have Rust installed (preferrably using your distributions package manager, but you can also use rustup) and then run the following command:

cargo install --locked cargo-doc2readme

Usage

To generate your readme, simply run

cargo doc2readme

This will output the readme to a file called README.md, using README.j2 or the built-in template.

Custom template

cargo doc2readme comes with a builtin template for your readme. You can view this template here. You can also provide your own template, either by placing a file called README.j2 next to your readme, by using the command line flag, or by using the config file. The template is in Jinja 2 format and will be parsed by minijinja. Please see TemplateContext for a list of all available placeholders.

Usage in CI

If you want to run this using Forgejo or GitHub Actions, you can use the pre-built docker image:

readme:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: docker://codeberg.org/msrd0/cargo-doc2readme
      with:
        entrypoint: cargo
        args: doc2readme --check

This will use the latest stable Rust version available when the latest release of cargo doc2readme was created. If you need a newer/nightly Rust compiler, use the codeberg.io/msrd0/cargo-doc2readme:nightly docker image instead.

Features

parse markdown from your rustdoc comments and embed it into your readme
use existing crates to parse Rust and Markdown
support your [CustomType] rustdoc links
default, minimalistic readme template with some useful badges
custom readme templates

Non-Goals

The following list may or may not describe the current functionality of cargo doc2readme. However, there is explicitly no guarantee for that in the future nor will it be considered a bug if they stop describing the current state.

verbatim copy of your markdown
easy readability of the generated markdown source code

Similar tools

cargo readme is a similar tool. However, it brings its own Rust code parser that only covers the 95% use case. Also, it does not support Rust path links introduced in Rust 1.48, making your readme ugly since the unsupported links are shown as raw markdown, and being less convenient for the reader that has to search docs.rs instead of clicking on a link.

cargo rdme is another tool which places your rustdoc into your readme. However, it does not come with template support, which is helpful for bigger repositories that contain multiple crates, and has only very basic support for Rust path links. All links not starting with crate:: or ::std are unsupported by cargo rdme.

Why not just `#![doc = include_str!("../README.md")]`?

For simple cases, doing the above will work just fine. However, this approach has several drawbacks:

No intra-doc links (which was the main motivation behind writing cargo doc2readme in the first place).
There is no possibility to add content to the git-repo’s or crates.io’s readme that is not shown by rustdoc.

Some projects may choose to add content to their readme that is only relevant to developers and/or people looking at the source code (for example, explaining the folder structure, or the contribution process). Those information is not relevant for the docs.rs page.
There is no possibility to inject information from the environment.

Some projects may, for example, choose to give you a line or two of content for your Cargo.toml. I’ve seen too many projects tell you to write foo = "*". Please don’t do that. Either use
```
#![doc = concat!(env!("CARGO_PKG_NAME"), " = \"", env!("CARGO_PKG_VERSION"), "\"")]
```
if you want it to show up on docs.rs, or use
```
{{ crate }} = "{{ crate_version }}"
```
in the readme template.

See TemplateContext for a list of all available placeholders, and The Cargo Book for a list of all environment variables set by cargo at compile time.
There is no way to hide code from the example codeblocks in your readme.

In order for the doc tests to be able to verify that your code compiles, you often need setup code. This code is likely not relevant for the example, and should therefore be hidden. In rustdoc, you can prefix those lines with a sharp (#) to hide them. cargo doc2readme knows this and does not add those lines to your readme.
If you create a codeblock with a flag, for example ```edition2021, your markdown previewer will interpret that as the language of the codeblock. rustdoc and cargo doc2readme remove those flags, and add rust as the language to all codeblocks.
rustfmt will not format your example code. If you use nightly rustfmt and set format_code_in_doc_comments = true (which I highly recommend), rustfmt will format all example code in Rust before it gets written by cargo doc2readme into your readme.

Stability Guarantees

This project adheres to semantic versioning. All versions will be tested against the latest stable rust version at the time of the release. All non-bugfix changes to the rustdoc input processing and markdown output or the default readme template are considered breaking changes, as well as any non-backwards-compatible changes to the command-line arguments or to these stability guarantees. All other changes, including any changes to the Rust code, or bumping the MSRV, are not considered breaking changes.

cargo-doc2readme 0.7.0