cargo-onedoc

📝 Generate README.md from doc comments.

Only write your documentation once! This crate provides a Cargo subcommand that can generate Markdown files from your Rust doc comments.

🚀 Getting started

First, install the tool using cargo

cargo install cargo-onedoc

Then generate your README from your lib.rs using the following.

cargo onedoc

This will generate a README using the default template. See config for how to configure how files are generated.

🌟 Features

This tool can take one or more Markdown files and/or Rust source files and output a single Markdown file.

When converting between Rustdoc Markdown and CommonMark, the following changes are made.

Headings

Headings are increased by one level. E.g. # becomes ##. For example:

//! ## MSRV
//!
//! Currently the minimum supported version is 1.51.0.

Will become

### MSRV

Currently the minimum supported version is 1.51.0.

Codeblocks

Bare codeblocks are fenced as Rust codeblocks e.g. ```rust. Leading # comments from codeblocks are removed. For example the following doc comment

//! ```
//! # fn main() {
//! println!("Hello, world!");
//! # }
//! ```

Will become

```rust
println!("Hello, world!");
```

Intradoc links

Intra doc links are converted based on the the links section of the config. For example assuming the following config:

[links]
"String" = "https://doc.rust-lang.org/stable/std/string/struct.String.html"

The following doc comment

//! Render the template to a [`String`].

Will become

Render the template to a [`String`][String].

[String]: https://doc.rust-lang.org/stable/std/string/struct.String.html

👷 Config

This tool can be configured using a onedoc.toml file. There are three main sections badges, doc and links.

badges

The badges settings are only relevant if you use the default README template.

[badges]
crates_io = true  # whether to add a badge for the crates.io page
docs_rs = true    # whether to add a badge for the docs.rs page

# optional badge for a github workflow
# name should be the name of the github workflow
github_workflow = { label = "build", name = "build" }

doc

The doc section is used to specify the input files and the output file. The input field is a list of files to read. The output field is the file to write to. The template field is the template file to use.

Here is an example from the sheldon repository. This constructs a README.md using multiple Markdown files.

[[doc]]
input = [
    "docs/src/Installation.md",
    "docs/src/Getting-started.md",
    "docs/src/Command-line-interface.md",
    "docs/src/Configuration.md",
]
output = "README.md"
template = "docs/README_TEMPLATE.md"

Here is another example from the upon repository.

[[doc]]
input = "src/syntax.rs"
output = "SYNTAX.md"
template = "docs/SYNTAX_TEMPLATE.md"

This constructs SYNTAX.md from the given Rust module and provided template.

links

The links is used to specific intra doc link mapping. This is needed because this tool does not figure out the correct link to use. This is simply a mapping of the link text to the URL.

[links]
"Display" = "https://doc.rust-lang.org/stable/std/fmt/trait.Display.html"

License

This project is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.