{"id":21214903,"url":"https://github.com/hadronized/cargo-sync-readme","last_synced_at":"2025-07-10T11:30:46.278Z","repository":{"id":34238509,"uuid":"172371011","full_name":"hadronized/cargo-sync-readme","owner":"hadronized","description":"Generate a Markdown section in your README based on your Rust documentation","archived":false,"fork":false,"pushed_at":"2023-01-20T04:04:15.000Z","size":184,"stargazers_count":58,"open_issues_count":11,"forks_count":13,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-20T14:20:10.257Z","etag":null,"topics":[],"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/hadronized.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-24T17:58:56.000Z","updated_at":"2024-10-11T11:45:52.000Z","dependencies_parsed_at":"2023-02-11T23:30:35.568Z","dependency_job_id":null,"html_url":"https://github.com/hadronized/cargo-sync-readme","commit_stats":null,"previous_names":["hadronized/cargo-sync-readme","phaazon/cargo-sync-readme"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hadronized%2Fcargo-sync-readme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hadronized%2Fcargo-sync-readme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hadronized%2Fcargo-sync-readme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hadronized%2Fcargo-sync-readme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hadronized","download_url":"https://codeload.github.com/hadronized/cargo-sync-readme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225633191,"owners_count":17499922,"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":[],"created_at":"2024-11-20T21:32:09.097Z","updated_at":"2024-11-20T21:32:21.478Z","avatar_url":"https://github.com/hadronized.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- cargo-sync-readme start --\u003e\n\n# `cargo sync-readme`\n\n**A plugin that generates a Markdown section in your README based on your Rust documentation.**\n\n## How does this work?\n\nBasically, this tool provides you with a simple mechanism to synchronize your front page\ndocumentation from your `lib.rs` or `main.rs` with a place in your *readme* file. In order to do\nso, this command will parse your inner documentation (i.e. `//!`) on `lib.rs` or `main.rs` and\nwill output it in your *readme* file at specific markers.\n\n## The markers\n\nBecause you might want a specific *readme* file that adds some more information to the\ndocumentation from your Rust code, this tool allows you to select a place where to put the\ndocumentation. This is done with three markers:\n\n- `\u003c!-- cargo-sync-readme --\u003e`: that annotation must be placed in your *readme* file where you\n  want the Rust documentation to be included and synchronized.\n- `\u003c!-- cargo-sync-readme start --\u003e`: that annotation is automatically inserted by the command\n  to delimit the beginning of the synchronized documentation.\n- `\u003c!-- cargo-sync-readme end --\u003e`: that annotation is automatically inserted by the command\n  to delimit the ending of the synchronized documentation.\n\n**You only have to use the former marker (i.e. `\u003c!-- cargo-sync-readme --\u003e`).** The rest of the\nmarkers will be handled automatically for you by the tool.\n\n\u003e Okay, but I want to change the place of the documentation now.\n\nWhen you have already put the synchronized documentation in your *readme* but want to change its\nlocation, all you have to do is remove everything in between the start and end annotations\n(annotations included) and place the `\u003c!-- cargo-sync-readme --\u003e` annotation wherever you want\nyour synchronized documentation to appear.\n\n## How should I use this?\n\nFirst, this tool will respect what you put in your `Cargo.toml`. There is a special field called\n`readme` that gives the name / path of the document you want to use as *readme* file.\n`cargo sync-readme` will operate on that file.\n\n\u003e Disclaimer: even though crates.io’s documentation and manifest format doesn’t explicitly state\n\u003e the type of this file, **`cargo sync-readme` assumes it’s Markdown.** If you want a support\n\u003e for another file type, please open an issue or a PR: those are warmly welcomed — and if you\n\u003e live in Paris, I offer you a Kwak or a Chouffe! ♥\n\nOnce you have put the annotation in your *readme* file, just run the command without argument to\nperform the synchronization:\n\n```text\ncargo sync-readme\n```\n\nThis will effectively update your *readme* file with the main documentation from your Rust code\n(either a `lib.rs` or `main.rs`, depending on the type of your crate).\n\n## Intra-link support\n\n\u003e This feature is new and lacks testing.\n\nThis tool rewrites intra-links so they point at the corresponding place in\n[docs.rs](https://docs.rs). The intra-links must be of the form `[⋯](crate::⋯)`.\n\nThe regular shortcut notation (using `[foo]: crate::foo` at the end of your Markdown document\nand using `[foo]` everywhere else) is not currently supported.\n\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`.\n\nPlease note that there are some limitations to intra-link support. To create the links we have\nto parse the source code to find out the class of the symbol being referenced (whether it is a\n`struct`, `trait`, etc). That necessarily imposes some restrictions, for instance, we will not\nexpand macros so symbols defined in macros will not be linkable.\n\n## Switches and options\n\nThe command has several options and flags you can use to customize the experience (a bit like a\nDisneyland Parc experience, but less exciting).\n\n- `-z` or `--show-hidden-doc`: this flag will disable a special transformation on your\n  documentation when copying into the region you’ve selected in your *readme*. All\n  ignored / hidden lines (the ones starting with a dash in code block in Rust doc) will simply\n  be dropped by default. This might be wanted if you want your *readme* documentation to look\n  like the one on docs.rs, where the hidden lines don’t show up. If you don’t, use this flag\n  to disable this behavior.\n- `-f` or `--prefer-doc-from`: this option allows you to override the place where to get the\n  documentation from. This might be wanted to override the default behavior that reads from\n  the Cargo.toml manifest, the autodetection based on files or when you have both a binary\n  and library setup (in which case this option is mandatory).\n- `--crlf`: this flag makes the tool’s newlines behaves according to CRLF. It will not change\n  the already present newlines but expect your document to be formatted with CRLF. If it’s\n  not then you will get punched in the face by a squirrel driving a motorcycle. Sorry. Also,\n  it will generate newlines with CRLF.\n- `-c --check`: check whether the *readme* is synchronized.\n\n## Q/A and troubleshooting\n\n### Are workspace crates supported?\n\nNot yet! If you have ideas how the tool should behave with them, please contribute with an issue or\na PR!\n\n\u003c!-- cargo-sync-readme end --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhadronized%2Fcargo-sync-readme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhadronized%2Fcargo-sync-readme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhadronized%2Fcargo-sync-readme/lists"}