Cargo command to create the README.md from your crate's documentation

Overview

Build Status Code Coverage Dependency status crates.io Downloads Github stars License

Cargo rdme

Cargo command to create your README from your crate’s documentation.

Installation

You can install cargo rdme with cargo by running cargo install cargo-rdme.

Usage

Cargo rdme will insert your crate’s documentation in your README file. To control where the documentation will be inserted you need to insert a marker: <!-- cargo-rdme -->. For example, you can start your README with some glorious badges and follow up with the rustdoc documentation:

[![Build Status](https://example.org/badge.svg)](https://example.org/link-to-ci)

<!-- cargo-rdme -->

After running cargo rdme you will find your README to be something like:

[![Build Status](https://example.org/badge.svg)](https://example.org/link-to-ci)

<!-- cargo-rdme start -->

<WHATEVER-YOUR-CRATES-DOC-IS>

<!-- cargo-rdme end -->

Whenever change your crate’s documentation you just need to run cargo rdme to update your README file.

Automatic transformations

The documentation of your crate doesn’t always map directly to a good README. For example, rust code blocks can have hidden lines. Those should not be shown in the README file.

This section covers the transformation cargo rdme automatically apply to generate a better README.

Rust code block

Rust code block are transformed in two ways by cargo rdme:

  1. Rust code blocks with lines starting with # will be omitted, just like in rustdoc.
  2. Rust code blocks get annotated with the rust markdown tag so it gets proper syntax highlighting. We also remove tags that only concern rustdoc such as should_panic.

In the table below you can see an example of these modification. The code block now is tagged with rust and hidden lines were removed:

Crate’s rustdoc README.md
//! To check if a number is prime do:
//!
//! ```
//! # fn main() {
//! for i in 2.. {
//!     if is_prime(i) {
//!         println!("{}", i);
//!     }
//! }
//! # }
//! ```
To check if a number is prime do:

```rust
for i in 2.. {
    if is_prime(i) {
        println!("{}", i);
    }
}
```

Intralinks

Rust documentation can contain links to items defined in the crate. This links would not make sense in your README file, so cargo rdme automatically generate links to docs.rs for these intralinks.

Currently we only support links of the form [⋯](crate::⋯), so be sure to use that format. Links to the standard library are also supported, and they must be of the form [⋯](::<crate>::⋯), where <crate> is a crate that is part of the standard library, such as std, core, or alloc.

Take a look at the example below:

Crate’s rustdoc README.md
//! To check if a number is prime use
//! [`is_prime`](crate::is_prime).
To check if a number is prime use
[`is_prime`](https://docs.rs/prime/latest/prime/fn.is_prime.html).

Note that there is some limitations in intralink support. This is a complex feature: cargo rdme needs to do some work to be able to create the link to docs.rs. This is because the link includes the kind of item the intralink points to, in the case of is_prime we need to discover that is a function to generate a link that ends in fn.is_prime.html. Therefore, intralink support should be considered "best effort" (for instance, don’t expect items generated by macros to be resolved). If cargo rdme is unable to generate the link it will still generate the README file, but a warning will be emitted.

Configuration file

If the default behavior of cargo rdme is not appropriate for your project you can crate a configuration file .cargo-rdme.toml in the root of your project. This is how that configuration file can look like:

# Override the README file path.  When this is not set cargo rdme will use the file path defined
# in the project’s `Cargo.toml`.
readme-path = "MY-README.md"

# What line terminator to use when generating the README file.  This can be "lf" or "crlf".
line-terminator = "lf"

# If you are using a workspace to hold multiple projects, use this to select the project from
# which to extract the documentation from.  It can be useful to also set `readme-path` to create
# the README file in the root of the project.
workspace-project = "subproject"

# The default entrypoint will be `src/lib.rs`.  You can change that in the `entrypoint` table.
[entrypoint]
# The entrypoint type can be "lib" or "bin".
type = "bin"
# When you set type to "bin" the entrypoint default to `src/main.rs`.  If you have binary targets
# specified in your cargo manifest you can select them by name with `bin-name`.
bin-name = "my-bin-name"

These setting can be overridden with command line flags. Run cargo rdme --help for more information.

Integration with CI

To verify that your README is up to date with your crate’s documentation you can run cargo rdme --check. The exit code will be 0 if the README is up to date, 2 if it’s not, or 4 if there were warnings.

Issues
  • Support workspaces

    Support workspaces

    null

    enhancement new-feature 
    opened by orium 1
  • Bump proc-macro2 from 1.0.30 to 1.0.32

    Bump proc-macro2 from 1.0.30 to 1.0.32

    Bumps proc-macro2 from 1.0.30 to 1.0.32.

    Release notes

    Sourced from proc-macro2's releases.

    1.0.32

    1.0.31

    • Update Cargo metadata to new repository location
    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    dependencies 
    opened by dependabot[bot] 1
  • Bump syn from 1.0.80 to 1.0.81

    Bump syn from 1.0.80 to 1.0.81

    Bumps syn from 1.0.80 to 1.0.81.

    Release notes

    Sourced from syn's releases.

    1.0.81

    • Support arbitrary precision negative literal tokens on rustc 1.56+ (#1087, #1088)
    Commits
    • 6044282 Release 1.0.81
    • f39a581 Merge pull request #1088 from dtolnay/literalparse
    • 0ca31d1 Delete lit overflow test
    • 793b1c3 Pull in proc-macro2 negative literal support
    • 3609334 Link to rustc PR for negative literal parse
    • a7eedc1 Locally ignore unnecessary_wraps pedantic clippy lint
    • d9a9ff4 Bypass negative literal workaround on 1.56+
    • 30984ec Merge pull request #1087 from dtolnay/literalparse
    • 0fda5ad Use 'FromStr for Literal' instead of TokenStream workaround
    • 68e7ab8 Suppress no_effect_underscore_binding pedantic Clippy lint in test suite
    • Additional commits viewable in compare view

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    dependencies 
    opened by dependabot[bot] 1
  • Bump git2 from 0.13.23 to 0.13.24

    Bump git2 from 0.13.23 to 0.13.24

    Bumps git2 from 0.13.23 to 0.13.24.

    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    dependencies 
    opened by dependabot[bot] 1
  • Support intralinks to primitive types

    Support intralinks to primitive types

    There is currently no way to link to usize or other primitive types.

    opened by orium 0
  • When we fail to generate the intralink link we should strip the link in the README

    When we fail to generate the intralink link we should strip the link in the README

    There's no point in preserving a link we know is broken.

    Makes sense to implement after #8.

    opened by orium 0
  • Option to remove intralinks

    Option to remove intralinks

    Some people might not want to have intralinks in the README file. A common case is an internal crate that doesn't have publish rustdoc anywhere. We should have an option to just strip away intralinks.

    This should be configurable in the config file as well as the command line argument.

    enhancement new-feature 
    opened by orium 0
  • Support intralinks using the

    Support intralinks using the "short syntax", e.g. [`foo::Foo`]

    For instance

    [`foo::Foo`]
    
    enhancement consolidation 
    opened by orium 0
  • Intralinks to identifiers that are exported do not work (the standard library does this a lot)

    Intralinks to identifiers that are exported do not work (the standard library does this a lot)

    Intralinks do not resolve re-exports. This means that if you have

    mod foo {
        pub mod bar {
            struct Bar {}
        }
    }
    
    pub use foo::bar;
    

    you cannot have an intralink to crate::bar::Bar, because re-exports are not resolved by cargo-rdme.

    This would be a reasonably acceptable limitation, if it wasn't a very common pattern in the standard library. For instance things defined in alloc are then re-exported in std, for instance, you cannot link to ::std::vec::Vec. This makes it a much more annoying limitation which deserves to be fixed.

    Something that we need to support is crate imports with rename (again, a common pattern in the standard library). For instance, this is how std::vec comes to be:

    extern crate alloc as alloc_crate;
    ⋮
    pub use alloc_crate::vec;
    

    This is independent from supporting use re-exports.

    bug consolidation 
    opened by orium 0
  • Allow intralink type to specified explicity

    Allow intralink type to specified explicity

    This is syntactically supported by rustdoc: https://doc.rust-lang.org/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators

    enhancement consolidation new-feature 
    opened by orium 0
Releases(v0.5.0)
  • v0.5.0(Nov 20, 2021)

  • v0.4.0(Nov 16, 2021)

    • Add support for intralinks!
      • Intralinks are not converted to links to docs.rs in your README file.
    • Add support for workspaces.
    • Add option to override the README file path (command line flag and configuration file).
    • Support code blocks with more than three backticks.
    • Use nice color output for errors and warnings.
    Source code(tar.gz)
    Source code(zip)
  • v0.3.0(Nov 1, 2021)

  • v0.2.0(Oct 31, 2021)

    • Rust code blocks starting with # are now omitted, just like in rustdoc.
    • Support default bin entrypoint paths.
    • Fix command line parsing bug when cargo-rdme was invoked as a cargo subcommand.
    Source code(tar.gz)
    Source code(zip)
  • v0.1.0(Oct 25, 2021)

    • Initial version.
    • Basic README syncronization.
    • Command line flags to control line terminator and entrypoint.
    • Support for configuration file.
    • Allow cargo rdme to be used easily integrated with CIs with the --check command line flag.
    Source code(tar.gz)
    Source code(zip)
Owner
Diogo Sousa
Diogo Sousa
Bundle Cargo crates for use with macOS/iOS in Xcode

cargo-cocoapods - Build Rust code for Xcode integration Installing cargo install cargo-cocoapods You'll also need to install all the toolchains you i

Brendan Molloy 6 Oct 24, 2021
Create ctags/etags for a cargo project

rusty-tags A command line tool that creates tags - for source code navigation by using ctags - for a cargo project, all of its direct and indirect dep

Daniel Trstenjak 334 Nov 22, 2021
The open source design documentation tool for everybody

Heads up: reimagining artifact 3.0, check it out at artifact_py Artifact: design documentation for everybody Note: this project, and the python re-wri

Rett Berg 567 Nov 20, 2021
Create evolving artistic images with hot-code-reloaded Lisp and GLSL.

Shadergarden is a tool for building hot-code-reloadable shader pipelines. For a tutorial for how to get started, consult the introductory

Tonari, Inc 92 Nov 22, 2021
gstats — command line tool to print a developer handy summary of all git repositories below current directory

gstats Simple Rust tool to get quick summary info on git repos showing latest tag, branch, state. I implemented this to help me work with a the not to

Boon at Shift 12 Jun 10, 2021
🤖 Just a command runner

just just is a handy way to save and run project-specific commands. (非官方中文文档,这里,快看过来!) Commands, called recipes, are stored in a file called justfile

Casey Rodarmor 3.9k Nov 24, 2021
🧑🏻‍⚕️ Command-line utility which poll on remote addresses in order to perform status checks periodically

ナース (Nāsu) ????‍⚕️ Command-line utility which poll on remote addresses in order to perform status checks periodically Motivation Nāsu (from Japanese ナ

Esteban Borai 13 Nov 14, 2021
Generate beautiful changelogs from your Git commit history

clog-cli A conventional changelog for the rest of us About clog creates a changelog automatically from your local git metadata. See the clogs changelo

Clog 736 Nov 21, 2021
A web service that generates images of dependency graphs for crates hosted on crates.io

crate-deps A web service that generates images of dependency graphs for crates hosted on crates.io This project is built entirely in Rust using these

Corey Farwell 20 Nov 9, 2020
crates is an extension aims to help people to manage their dependencies for rust (crates.io & TOML).

crates Hello Rust & VSCode lovers, This is crates, an extension for crates.io dependencies. Aims helping developers to manage dependencies while using

Seray Uzgur 128 Nov 10, 2021
https://crates.io/crates/transistor

Transistor A Rust Crux Client crate/lib. For now, this crate intends to support 2 ways to interact with Crux: Via Docker with a crux-standalone versio

Julia Naomi 27 Oct 21, 2021
Bundle Cargo crates for use with macOS/iOS in Xcode

cargo-cocoapods - Build Rust code for Xcode integration Installing cargo install cargo-cocoapods You'll also need to install all the toolchains you i

Brendan Molloy 6 Oct 24, 2021
Add a cute dependency declaration snippet in your crate documentation.

dep_doc Add a cute dependency declaration snippet in your crate documentation. Adding to Cargo.toml [dependencies] dep_doc = "0.1.1" Goal When writing

Sasha 35 Nov 24, 2021
A cargo plugin to shrink cargo's output

cargo single-line A simple cargo plugin that shrinks the visible cargo output to a single line (okay, in the best case scenario). In principle, the pl

Denis 4 Sep 29, 2021
cargo extension for flashing embedded rust programs via dfu based on jacobrosenthals cargo-hf2

cargo-dfu This crate provides a cargo subcommand to flash ELF binaries via dfu Most STM chips will probably work with this, although you might need to

Roman Kretschmer 1 Nov 14, 2021
Create ctags/etags for a cargo project

rusty-tags A command line tool that creates tags - for source code navigation by using ctags - for a cargo project, all of its direct and indirect dep

Daniel Trstenjak 334 Nov 22, 2021
Cargo subcommand to automatically create universal libraries for iOS.

cargo lipo Provides a cargo lipo subcommand which automatically creates a universal library for use with your iOS application. Maintenance Status Plea

Tim Neumann 335 Nov 17, 2021
A CLI tool that allow you to create a temporary new rust project using cargo with already installed dependencies

cargo-temp A CLI tool that allow you to create a new rust project in a temporary directory with already installed dependencies. Install Requires Rust

Yohan Boogaert 34 Nov 24, 2021
Temporary edit external crates that your project depends on

rhack You want to quickly put a sneaky macro kind of like dbg! into external crates to find out how some internal data structure works? If so rhack is

Ryo Nakao 98 Nov 9, 2021
The open source design documentation tool for everybody

Heads up: reimagining artifact 3.0, check it out at artifact_py Artifact: design documentation for everybody Note: this project, and the python re-wri

Rett Berg 567 Nov 20, 2021
The public source and documentation for Xenon iOS tweak.

THE GUIDE HAS BEEN MOVED TO THE WIKI This is the public source for the Xenon iOS tweak. The full version is available for $1.99 on Chariz. Differences

aspen 6 Nov 2, 2021
Doku is a framework for building documentation with code-as-data methodology in mind.

Doku is a framework for building documentation with code-as-data methodology in mind. Say goodbye to stale, hand-written documentation - with D

ANIXE 63 Nov 14, 2021
Frame is a markdown language for creating state machines (automata) in 7 programming languages as well as generating UML documentation.

Frame Language Transpiler v0.5.1 Hi! So very glad you are interested in Frame. Frame system design markdown language for software architects and engin

Mark Truluck 20 Nov 26, 2021
Rust Cargo command bindings

Vim Cargo Simple vim command bindings to quickly run cargo stuff from vim. Commands Available, mapping with their Cargo equivalant: CargoBench CargoBu

Timon Vonk 41 Jul 22, 2021
A very simple third-party cargo subcommand to execute a custom command

cargo-x A very simple third-party cargo subcommand to execute a custom command Usage install cargo-x cargo install cargo-x or upgrade cargo install -

刘冲 7 Jun 21, 2021
Docker images for compiling static Rust binaries using musl-libc and musl-gcc, with static versions of useful C libraries. Supports openssl and diesel crates.

rust-musl-builder: Docker container for easily building static Rust binaries Source on GitHub Changelog UPDATED: Major updates in this release which m

Eric Kidd 1k Nov 24, 2021
A lean, minimal, and stable set of types for color interoperation between crates in Rust.

This library provides a lean, minimal, and stable set of types for color interoperation between crates in Rust. Its goal is to serve the same function that mint provides for (linear algebra) math types.

Gray Olson 13 Oct 5, 2021
Lagoon is a thread pool crate that aims to address many of the problems with existing thread pool crates.

Lagoon is a thread pool crate that aims to address many of the problems with existing thread pool crates. Example Lagoon's scoped jobs can be u

Joshua Barretto 18 Nov 7, 2021