📝 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.
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 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.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!");
```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).This tool can be configured using a onedoc.toml file. There are two main
sections doc and links.
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"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"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.