{"id":13930199,"url":"https://github.com/webern/cargo-readme","last_synced_at":"2026-04-09T21:16:55.750Z","repository":{"id":41502815,"uuid":"43921761","full_name":"webern/cargo-readme","owner":"webern","description":"Generate README.md from docstrings","archived":false,"fork":false,"pushed_at":"2024-04-02T23:45:35.000Z","size":247,"stargazers_count":339,"open_issues_count":54,"forks_count":56,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-19T11:12:18.833Z","etag":null,"topics":["cargo-readme","cargo-subcommand","readme","rust"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webern.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-08T23:29:49.000Z","updated_at":"2024-06-18T21:29:53.712Z","dependencies_parsed_at":"2024-01-18T04:08:15.690Z","dependency_job_id":"f201dd26-f510-4512-bfeb-c5844e17fdfe","html_url":"https://github.com/webern/cargo-readme","commit_stats":null,"previous_names":["webern/cargo-readme"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webern%2Fcargo-readme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webern%2Fcargo-readme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webern%2Fcargo-readme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webern%2Fcargo-readme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webern","download_url":"https://codeload.github.com/webern/cargo-readme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247773719,"owners_count":20993639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cargo-readme","cargo-subcommand","readme","rust"],"created_at":"2024-08-07T18:05:07.348Z","updated_at":"2026-04-09T21:16:55.714Z","avatar_url":"https://github.com/webern.png","language":"Rust","funding_links":[],"categories":["rust","Rust"],"sub_categories":[],"readme":"[![Crates.io](https://img.shields.io/crates/v/cargo-readme.svg)](https://crates.io/crates/cargo-readme)\n[![Workflow Status](https://github.com/webern/cargo-readme/workflows/main/badge.svg)](https://github.com/webern/cargo-readme/actions?query=workflow%3A%22main%22)\n\n# cargo-readme\n\nGenerate README.md from doc comments.\n\nCargo subcommand that extract documentation from your crate's doc comments that you can use to\npopulate your README.md.\n\n#### Attribution\n\nThis library was authored by Livio Ribeiro ([@livioribeiro](https://github.com/livioribeiro))\nand originally located at `https://github.com/livioribeiro/cargo-readme`, which now redirects\nhere (as of August 2023). Thank you, Livio, for this lib!\n\n## Installation\n\n```sh\ncargo install cargo-readme\n```\n\n## Motivation\n\nAs you write documentation, you often have to show examples of how to use your software. But\nhow do you make sure your examples are all working properly? That we didn't forget to update\nthem after a breaking change and left our (possibly new) users with errors they will have to\nfigure out by themselves?\n\nWith `cargo-readme`, you just write the rustdoc, run the tests, and then run:\n\n```sh\ncargo readme \u003e README.md\n```\n\nAnd that's it! Your `README.md` is populated with the contents of the doc comments from your\n`lib.rs` (or `main.rs`).\n\n## Usage\n\nLet's take the following rust doc:\n\n```rust\n//! This is my awesome crate\n//!\n//! Here goes some other description of what it is and what is does\n//!\n//! # Examples\n//! ```\n//! fn sum2(n1: i32, n2: i32) -\u003e i32 {\n//!   n1 + n2\n//! }\n//! # assert_eq!(4, sum2(2, 2));\n//! ```\n```\n\nRunning `cargo readme` will output the following:\n\n~~~markdown\n[![Build Status](__badge_image__)](__badge_url__)\n\n# my_crate\n\nThis is my awesome crate\n\nHere goes some other description of what it is and what is does\n\n## Examples\n```rust\nfn sum2(n1: i32, n2: i32) -\u003e i32 {\n  n1 + n2\n}\n```\n\nLicense: MY_LICENSE\n~~~\n\nLet's see what's happened:\n\n- a badge was created from the one defined in the `[badges]` section of `Cargo.toml`\n- the crate name (\"my-crate\") was added\n- \"# Examples\" heading became \"## Examples\"\n- code block became \"```rust\"\n- hidden line `# assert_eq!(4, sum2(2, 2));` was removed\n\n`cargo-readme` also supports multiline doc comments `/*! */` (but you cannot mix styles):\n\n~~~rust\n/*!\nThis is my awesome crate\n\nHere goes some other description of what it is and what is does\n\n```\nfn sum2(n1: i32, n2: i32) -\u003e i32 {\n  n1 + n2\n}\n```\n*/\n~~~\n\nIf you have additional information that does not fit in doc comments, you can use a template.\nJust create a file called `README.tpl` in the same directory as `Cargo.toml` with the following\ncontent:\n\n```tpl\n{{badges}}\n\n# {{crate}}\n\n{{readme}}\n\nCurrent version: {{version}}\n\nSome additional info here\n\nLicense: {{license}}\n```\n\nThe output will look like this\n\n~~~markdown\n[![Build Status](__badge_image__)](__badge_url__)\n\n# my_crate\n\nCurrent version: 3.0.0\n\nThis is my awesome crate\n\nHere goes some other description of what it is and what is does\n\n## Examples\n```rust\nfn sum2(n1: i32, n2: i32) -\u003e i32 {\n  n1 + n2\n}\n```\n\nSome additional info here\n\nLicense: MY_LICENSE\n~~~\n\nBy default, `README.tpl` will be used as the template, but you can override it using the\n`--template` to choose a different template or `--no-template` to disable it.\n\n## License\n\nLicensed under either of\n\n* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)\n* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally\nsubmitted for inclusion in the work by you, as defined in the Apache-2.0\nlicense, shall be dual licensed as above, without any additional terms or\nconditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebern%2Fcargo-readme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebern%2Fcargo-readme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebern%2Fcargo-readme/lists"}