{"id":13594974,"url":"https://github.com/orium/cargo-rdme","last_synced_at":"2025-05-16T04:03:37.993Z","repository":{"id":36979613,"uuid":"415380386","full_name":"orium/cargo-rdme","owner":"orium","description":"Cargo command to create the README.md from your crate's documentation","archived":false,"fork":false,"pushed_at":"2025-04-11T18:07:53.000Z","size":391,"stargazers_count":157,"open_issues_count":22,"forks_count":6,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-11T19:26:25.825Z","etag":null,"topics":["readme","readme-template"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2021-10-09T17:43:30.000Z","updated_at":"2025-04-11T18:04:59.000Z","dependencies_parsed_at":"2023-11-28T22:27:44.042Z","dependency_job_id":"66cf58ae-ded5-4165-b5c6-51993268a5d8","html_url":"https://github.com/orium/cargo-rdme","commit_stats":{"total_commits":196,"total_committers":5,"mean_commits":39.2,"dds":0.04081632653061229,"last_synced_commit":"964a939c8c86a2e6aa3f6a8f89cf75b64ab92f6a"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orium%2Fcargo-rdme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orium%2Fcargo-rdme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orium%2Fcargo-rdme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orium%2Fcargo-rdme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orium","download_url":"https://codeload.github.com/orium/cargo-rdme/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254464891,"owners_count":22075570,"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":["readme","readme-template"],"created_at":"2024-08-01T16:01:41.705Z","updated_at":"2025-05-16T04:03:37.937Z","avatar_url":"https://github.com/orium.png","language":"Rust","funding_links":[],"categories":["Rust","开发工具 Development tools","Development tools"],"sub_categories":["构建系统 Build system","Build system"],"readme":"[![Build Status](https://github.com/orium/cargo-rdme/workflows/CI/badge.svg)](https://github.com/orium/cargo-rdme/actions?query=workflow%3ACI)\n[![Code Coverage](https://codecov.io/gh/orium/cargo-rdme/branch/main/graph/badge.svg)](https://codecov.io/gh/orium/cargo-rdme)\n[![Dependency status](https://deps.rs/repo/github/orium/cargo-rdme/status.svg)](https://deps.rs/repo/github/orium/cargo-rdme)\n[![crates.io](https://img.shields.io/crates/v/cargo-rdme.svg)](https://crates.io/crates/cargo-rdme)\n[![Downloads crates.io](https://img.shields.io/crates/d/cargo-rdme.svg?label=crates.io%20downloads)](https://crates.io/crates/cargo-rdme)\n[![Downloads github](https://img.shields.io/github/downloads/orium/cargo-rdme/total.svg?label=github%20downloads)](https://github.com/orium/cargo-rdme/releases)\n[![Github stars](https://img.shields.io/github/stars/orium/cargo-rdme.svg?logo=github)](https://github.com/orium/cargo-rdme/stargazers)\n[![License](https://img.shields.io/crates/l/cargo-rdme.svg)](./LICENSE.md)\n\n# Cargo rdme\n\n\u003c!-- cargo-rdme start --\u003e\n\nCargo command to create your README from your crate’s documentation.\n\n## Installation\n\nYou can install cargo rdme with cargo by running `cargo install cargo-rdme`.\n\n## Usage\n\nCargo rdme will insert your crate’s documentation in your README file.  To control where the\ndocumentation will be inserted you need to insert a marker: `\u003c!-- cargo-rdme --\u003e`.  For example,\nyou can start your README with some glorious badges and follow up with the rustdoc\ndocumentation:\n\n```markdown\n[![Build Status](https://example.org/badge.svg)](https://example.org/link-to-ci)\n\n\u003c!-- cargo-rdme --\u003e\n```\n\nAfter running `cargo rdme` you will find your README to be something like:\n\n```markdown\n[![Build Status](https://example.org/badge.svg)](https://example.org/link-to-ci)\n\n\u003c!-- cargo-rdme start --\u003e\n\n\u003cWHATEVER-YOUR-CRATES-DOC-IS\u003e\n\n\u003c!-- cargo-rdme end --\u003e\n```\n\nWhenever change your crate’s documentation you just need to run `cargo rdme` to update your\nREADME file.\n\n## Automatic transformations\n\nThe documentation of your crate doesn’t always map directly to a good README.  For example,\nrust code blocks can have hidden lines.  Those should not be shown in the README file.\n\nThis section covers the transformation cargo rdme automatically apply to generate a better\nREADME.\n\n### Rust code block\n\nRust code block are transformed in two ways by cargo rdme:\n\n1. Rust code blocks with lines starting with `#` will be omitted, just like in `rustdoc`.\n2. Rust code blocks get annotated with the `rust` markdown tag so it gets proper syntax\n   highlighting.  We also remove tags that only concern `rustdoc` such as `should_panic`.\n\nIn the table below you can see an example of these modification.  The code block now is\ntagged with `rust` and hidden lines were removed:\n\n\u003ctable border=\"1\"\u003e\n\u003ccol span=\"1\" width=\"40%\"\u003e\n\u003ccol span=\"1\" width=\"40%\"\u003e\n\u003c/colgroup\u003e\n\u003ctr\u003e\n\u003cth\u003e\u003ccenter\u003eCrate’s rustdoc\u003c/center\u003e\u003c/th\u003e\n\u003cth\u003e\u003ccenter\u003eREADME.md\u003c/center\u003e\u003c/th\u003e\n\u003ctr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```rust\n//! To check if a number is prime do:\n//!\n//! ```\n//! # fn main() {\n//! for i in 2.. {\n//!     if is_prime(i) {\n//!         println!(\"{i}\");\n//!     }\n//! }\n//! # }\n//! ```\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n````markdown\nTo check if a number is prime do:\n\n```rust\nfor i in 2.. {\n    if is_prime(i) {\n        println!(\"{i}\");\n    }\n}\n```\n````\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### Intralinks\n\nRust documentation can contain [links to items defined in the crate](https://doc.rust-lang.org/stable/rustdoc/linking-to-items-by-name.html).\nThis links would not make sense in your README file, so cargo rdme automatically generate\nlinks to [docs.rs](https://docs.rs) for these intralinks.\n\nCurrently we only support links of the form `[⋯](crate::⋯)`, so be sure to use that format.\nLinks to the standard library are also supported, and they must be of the form\n`[⋯](::\u003ccrate\u003e::⋯)`, where `\u003ccrate\u003e` is a crate that is part of the standard library, such as\n`std`, `core`, or `alloc`.  Reference-style links are also supported.\n\nTake a look at the example below:\n\n\u003ctable border=\"1\"\u003e\n\u003ccol span=\"1\" width=\"40%\"\u003e\n\u003ccol span=\"1\" width=\"40%\"\u003e\n\u003c/colgroup\u003e\n\u003ctr\u003e\n\u003cth\u003e\u003ccenter\u003eCrate’s rustdoc\u003c/center\u003e\u003c/th\u003e\n\u003cth\u003e\u003ccenter\u003eREADME.md\u003c/center\u003e\u003c/th\u003e\n\u003ctr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```rust\n//! To check if a number is prime use\n//! [`is_prime`](crate::is_prime).\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n```markdown\nTo check if a number is prime use\n[`is_prime`](https://docs.rs/prime/latest/prime/fn.is_prime.html).\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nNote that there is some limitations in intralink support.  This is a complex feature: cargo rdme\nneeds to do some work to be able to create the link to docs.rs.  This is because the link\nincludes the kind of item the intralink points to, in the case of `is_prime` we need to discover\nthat is a function to generate a link that ends in `fn.is_prime.html`.  Therefore, intralink\nsupport should be considered \"best effort\" (for instance, don’t expect items generated by macros\nto be resolved).  If cargo rdme is unable to generate the link it will still generate the README\nfile, but a warning will be emitted.\n\n### Heading levels\n\nThe heading levels in the crate’s documentation will, by default, be nested under the level\nof the section of the README where it is inserted into.  This behavior can be changed with\nthe `--heading-base-level` command line flag, or in the configuration file (see example\nbelow).\n\n## Configuration file\n\nIf the default behavior of `cargo rdme` is not appropriate for your project you can crate a\nconfiguration file `.cargo-rdme.toml` in the root of your project.  This is how that\nconfiguration file can look like:\n\n```toml\n# Override the README file path.  When this is not set cargo rdme will use the file path defined\n# in the project’s `Cargo.toml`.\nreadme-path = \"MY-README.md\"\n\n# What line terminator to use when generating the README file.  This can be \"lf\" or \"crlf\".\nline-terminator = \"lf\"\n\n# If you are using a workspace to hold multiple projects, use this to select the project from\n# which to extract the documentation from.  It can be useful to also set `readme-path` to create\n# the README file in the root of the project.\nworkspace-project = \"subproject\"\n\n# Defines the base heading level to use when inserting the crate’s documentation in the\n# README.  If this is not set the crate’s documentation will be inserted with its sections\n# belonging to the README section where the insertion happens.\nheading-base-level = 0\n\n# The default entrypoint will be `src/lib.rs`.  You can change that in the `entrypoint` table.\n[entrypoint]\n# The entrypoint type can be \"lib\" or \"bin\".\ntype = \"bin\"\n# When you set type to \"bin\" the entrypoint default to `src/main.rs`.  If you have binary targets\n# specified in your cargo manifest you can select them by name with `bin-name`.\nbin-name = \"my-bin-name\"\n\n[intralinks]\n# Defines the base url to use in intralinks urls.  The default value is `https://docs.rs`.\ndocs-rs-base-url = \"https://mydocs.rs\"\n# Defines the version to use in intralinks urls.  The default value is `latest`.\ndocs-rs-version = \"1.0.0\"\n# If this is set the intralinks will be stripping in the README file.\nstrip-links = false\n```\n\nThese setting can be overridden with command line flags.  Run `cargo rdme --help` for more\ninformation.\n\n## Integration with CI\n\nTo verify that your README is up to date with your crate’s documentation you can run\n`cargo rdme --check`.  The exit code will be `0` if the README is up to date, `3` if it’s\nnot, or `4` if there were warnings.\n\nIf you use GitHub Actions you can add this step to verify if the README is up to date:\n\n```yaml\n- name: Check if the README is up to date.\n  run: |\n    cargo install cargo-rdme\n    cargo rdme --check\n```\n\n\u003c!-- cargo-rdme end --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forium%2Fcargo-rdme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forium%2Fcargo-rdme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forium%2Fcargo-rdme/lists"}