snipdoc 0.1.6

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
80
81
82
83
84
85
86
87
88
89
90
91

# Snipdoc

**Snipdoc** is a straightforward tool for managing documentation that includes code snippets.
It collects snippets from your code or YAML files and injects them into various parts of your documentation, making the documentation process more efficient.

## Installation
#### Cargo install:
```sh
cargo install snipdoc
```
Or download from the [GitHub Repository.](https://github.com/kaplanelad/snipdoc/releases/latest)
## Getting started:

### Collecting Snippets
To collect snippets, follow these steps:
1. Identify the piece of content in your code that you want to grab.
2. Wrap the snippet with the following tag:
```text
// <snip id="SNIPPET_ID">
     CONTENT HERE
// </snip>
```
3. You can hide the snippet from presentation using various comment styles:
    - In Markdown files (like readme.md), use HTML comments: `<!-- CONTENT HERE -->`
    - In Rust file docs, use: `//! CONTENT HERE`
    - In Rust function docs, use: `/// CONTENT HERE`
    - Use appropriate comment tags for other file formats.

### Injecting Snippets
To inject snippets, create an empty placeholder with the snippet ID and add `inject_from="code"` attribute like this:

```text
<!-- <snip id="SNIPPET_ID" inject_from="code"> -->
     CONTENT HERE
<!-- </snip> -->
```

After adding the placeholder, run the following command:

```sh
snipdoc run
```

#### Inject attributes
Following attributes are available when injecting the snippets as a attribute.

##### add_prefix
For adding a prefix for each snippet line use the `add_prefix` attribute. 

##### strip_prefix
For removing a prefix for each snippet line use `strip_prefix` attribute

##### template
Wrap the snippet content with a custom template use `template` attribute.


### Managing Snippets

To manage all snippets effectively, run the following command:

```sh
snipdoc show
```

For a live example, run the following command inside your project:
```sh
 snipdoc show ./snipdoc/examples/inject
```

### Managing Snippets in YAML

If you prefer managing snippets in a YAML file, follow these steps:

1. Run the following command to create an empty `snipdoc.yml` file:
   ```sh
   snipdoc create-db --empty
   ```
2. Add your snippets to `snipdoc.yml`, and use them by injecting from YAML (`inject_from="code"`). 
For a live example, run the following command inside your project:
   ```sh
   snipdoc run ./snipdoc/examples/inject
   ```

### Check

validate that all snippets are valid and match the current injected versions. 
It is useful for incorporating into CI workflows to ensure documentation accuracy and consistency.

```sh
snipdoc check
```