๐ 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.