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.

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`](https://doc.rust-lang.org/stable/std/string/struct.String.html).

Config

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

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.

[[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"

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.