Crates.io | snipgrep |
lib.rs | snipgrep |
version | 0.1.0 |
source | src |
created_at | 2024-05-21 14:36:24.254836 |
updated_at | 2024-05-21 14:36:24.254836 |
description | Code Documentation Made Simple |
homepage | https://github.com/kaplanelad/snipgrep |
repository | https://github.com/kaplanelad/snipgrep |
max_upload_size | |
id | 1246895 |
size | 115,915 |
When working on open-source projects or internal projects, creating effective documentation is essential. As a developer, I often faced the challenge of generating and maintaining comprehensive project documentation. The example below demonstrates various types of documentation I've included:
However, a common issue is ensuring that the examples provided in the documentation remain accurate and up-to-date. What if the example code changes? What if there's a typo in the documented code? How can we ensure that the examples always reflect the current state of the codebase?
Imagine a tool that allows you to extract code snippets, ensuring they are
not only reliable but also executable. What if you could easily incorporate
pieces of code that are known to work or leverage tested examples from
languages like Rust, which use Doctest
? This tool is designed to address
these concerns.
My objectives are as follows:
The process begins with your project. Navigate to the section you wish to include in your documentation and enclose it with // <snipgrep id="introduction">
. Mark the end of the section with // </snipgrep>
.
For instance, it should resemble this in Rust:
// <snipgrep id="introduction">
fn add_numbers(a: i32, b: i32) -> i32 {
a + b
}
// </snipgrep>
Next, navigate to your documentation, such as the readme.md file, and begin the section with <!-- <snipgrep id="ID"> -->
. Conclude this section with // </snipgrep>
.
Upon executing the command rdocs replace [COLLECT-FOLDER] [DOC-FOLDER]
, all examples will be gathered and seamlessly replace the corresponding content in your documentation.
snipgrep create-db
- Create a local DB file in case you want to manage
the snippet via a filesnipgrep run
- Collect and inject the snippetCargo install:
cargo install snipgrep
snipgrep create-db
- Create a local DB file in case you want to manage
the snippet via a filesnipgrep run
- Collect and inject the snippet
GitHub Repository