snipgrep 0.1.0

Code Documentation Made Simple
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

# Snipgrep: Code Documentation Made Simple

<!-- <snipgrep id="introduction" inject strip_prefix="//!"> -->

 ## Introduction
 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:

 - Examples showcasing how to use the application configuration.
 - A README guide illustrating the usage of my CLI.
 - Code snippets demonstrating the usage of my library in different
   scenarios.

 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.
<!-- </snipgrep> -->

<!-- <snipgrep id="my-goal" inject strip_prefix="//!"> -->

 ## Goal
 My objectives are as follows:

 - **Alignment with Code:** Ensure documentation consistently aligns with the
   codebase.
 - **CI Validation:** Incorporate validation into Continuous Integration to
   ensure documentation validity.
 - **User-Friendly:** Prioritize ease of use for all stakeholders.
 - **Minimal Dependencies:** Enable documentation validity even without
   external tool dependencies.
<!-- </snipgrep> -->


## How It Works?
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:
```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 id="available-commands" inject strip_prefix="//!"> -->

 ## Available commands:
 - `snipgrep create-db` - Create a local DB file in case you want to manage
   the snippet via a file
 - `snipgrep run` - Collect and inject the snippet
<!-- </snipgrep> ->
<!-- <snipgrep id="installation" inject strip_prefix="//!"> -->

 ## Installation

 Cargo install:
 ```sh
 cargo install snipgrep
 ```
 ## Available commands:
 - `snipgrep create-db` - Create a local DB file in case you want to manage
   the snippet via a file
 - `snipgrep run` - Collect and inject the snippet
[GitHub Repository](https://github.com/kaplanelad/snipgrep/releases/latest)
<!-- </snipgrep> -->