{"id":18158284,"url":"https://github.com/sam0x17/docify","last_synced_at":"2025-04-05T01:04:25.086Z","repository":{"id":163614110,"uuid":"637964668","full_name":"sam0x17/docify","owner":"sam0x17","description":"Allows for dynamic compile-time embedding of existing tests and examples in your Rust doc comments and markdown files","archived":false,"fork":false,"pushed_at":"2025-02-21T04:41:29.000Z","size":276,"stargazers_count":26,"open_issues_count":11,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T00:05:02.693Z","etag":null,"topics":["documentation","documentation-tool","proc-macro","proc-macro-attributes","rust","rust-crate","rust-documentation","rust-lang"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sam0x17.png","metadata":{"files":{"readme":"README.docify.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2023-05-08T19:42:21.000Z","updated_at":"2025-02-21T04:41:07.000Z","dependencies_parsed_at":"2024-04-01T06:35:45.526Z","dependency_job_id":"d894fe6b-aef5-4d79-8d60-cc6feb8ad27a","html_url":"https://github.com/sam0x17/docify","commit_stats":{"total_commits":143,"total_committers":3,"mean_commits":"47.666666666666664","dds":0.04195804195804198,"last_synced_commit":"f5a69404652ce0de7b83413fdc69266550019cbe"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sam0x17%2Fdocify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sam0x17%2Fdocify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sam0x17%2Fdocify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sam0x17%2Fdocify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sam0x17","download_url":"https://codeload.github.com/sam0x17/docify/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247271519,"owners_count":20911587,"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":["documentation","documentation-tool","proc-macro","proc-macro-attributes","rust","rust-crate","rust-documentation","rust-lang"],"created_at":"2024-11-02T07:06:11.123Z","updated_at":"2025-04-05T01:04:25.065Z","avatar_url":"https://github.com/sam0x17.png","language":"Rust","readme":"# Docify\n\n[![Crates.io](https://img.shields.io/crates/v/docify)](https://crates.io/crates/docify)\n[![docs.rs](https://img.shields.io/docsrs/docify?label=docs)](https://docs.rs/docify/latest/docify/)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/sam0x17/docify/ci.yaml)](https://github.com/sam0x17/docify/actions/workflows/ci.yaml?query=branch%3Amain)\n[![MIT License](https://img.shields.io/github/license/sam0x17/docify)](https://github.com/sam0x17/docify/blob/main/LICENSE)\n\nThis crate provides a simple set of rust macros, namely\n[`#[docify::export]`](https://docs.rs/docify/latest/docify/attr.export.html) and\n[`docify::embed!`](https://docs.rs/docify/latest/docify/macro.embed.html), that allow you to\ndynamically embed tests and examples from the current crate or sub-crates of the current crate\ndirectly within rust docs comments, with the option to make these examples runnable.\n\nThe intent behind docify is to allow you to showcase your best examples and tests directly in\nyour docs, without having to update them in two places every time there is a change. It also\nencourages a methodology where crate authors better document their tests, since they can now\nshowcase these directly in their doc comments.\n\nAll-in-all this is a much better workflow than having doc examples isolated within your docs,\nsince you can avoid boilerplate from the surrounding code and just focus on showcasing the item\nyou want to highlight.\n\n## General Usage\n\nUsing `docify` is simple. First mark the tests/examples/items that you wish to embed with\n[`#[docify::export]`](https://docs.rs/docify/latest/docify/attr.export.html), such as the\nfollowing:\n\n```rust\n#[docify::export]\nfn some_example() {\n  assert_eq!(2 + 2, 4);\n  assert_eq!(2 + 3, 5);\n  assert_eq!(3 + 3, 6);\n}\n```\n\nYou can then embed this item directly in doc comments using the `docify::embed` macro:\n\n```rust\n/// These are some docs about an item. You can embed examples, tests, and\n/// other items directly into docs using the following macro:\n#[doc = docify::embed!(\"source/file/path.rs\", some_example)]\n/// More docs can go here, the example will embed itself inline exactly\n/// where you reference it.\npub struct SomeItem;\n```\n\nThis will result in the following expanded doc comments:\n\n```rust\n/// These are some docs about an item. You can embed examples,\n/// tests, and other items directly into docs using the\n/// following macro:\n/// ```ignore\n/// fn some_example() {\n///   assert_eq!(2 + 2, 4);\n///   assert_eq!(2 + 3, 5);\n///   assert_eq!(3 + 3, 6);\n/// }\n/// ```\n/// More docs can go here, the example will embed itself inline\n/// exactly where you reference it.\npub struct SomeItem;\n```\n\nYou can embed any item capable of having an attribute macro attached to it.\n\n## Runnable Examples\n\nNote that you can also use the\n[`embed_run!`](https://docs.rs/docify/latest/docify/macro.embed_run.html) version of the\nmacro to make the embedded example compile/run as part of doc tests, which is desirable in\ncertain situations even though typically the example will already be running/compiling\nsomewhere else in your project.\n\n## Markdown\n\nA newly added feature allows compiling markdown files with HTML comments\nthat contain regular `docify::embed!(..)` calls, with the option to compile entire directories\nof files or individual files.\n\nIn fact, this `README.md` file is automatically compiled whenever `cargo doc` is run on this\ncrate, resulting in the following codeblock to populate dynamically:\n\n\u003c!-- docify::embed!(\"examples/samples.rs\", some_example) --\u003e\n\nIf you look at the [source\ncode](https://raw.githubusercontent.com/sam0x17/docify/main/.README.docify.md) for\n`.README.docify.md`, you'll notice we use the following HTML comment to perform the above\nembedding:\n\n```markdown\n\u003c!-- docify::embed!(\"examples/samples.rs\", some_example) --\u003e\n```\n\nSee [`compile_markdown!`](https://docs.rs/docify/latest/docify/macro.compile_markdown.html) for more info.\n\n## More Info\n\nFor more documentation, features, and examples, check out [the docs](https://docs.rs/docify)!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsam0x17%2Fdocify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsam0x17%2Fdocify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsam0x17%2Fdocify/lists"}