Skip to content

๐Ÿ“ Generate your README.md from Rust doc comments

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT
Notifications You must be signed in to change notification settings

rossmacarthur/cargo-onedoc

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

23 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

cargo-onedoc

Crates.io Version Docs.rs Latest Build Status

๐Ÿ“ 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.

About

๐Ÿ“ Generate your README.md from Rust doc comments

Resources

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT

Stars

Watchers

Forks

Packages

No packages published

Languages