Crate 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

To install Snipdoc, you can use Cargo:

cargo install snipdoc

Or download it from the GitHub Repository.

Getting Started

To collect and replace all snippets from multiple data sources, use:

snipdoc run

For a detailed guide on how it works, follow this guid

Inject Options

Snipdoc provides several attributes to customize snippet injection:

Adding a Prefix to Snippets

The add_prefix attribute allows you to prepend a specified string to each line of the snippet. This is useful when you need to format the injected snippets with a specific prefix, such as for comments in code blocks.

Check out this example

Removing a Prefix from Snippets

The strip_prefix attribute allows you to remove a specified string from the beginning of each line in the snippet. This is useful when you need to format the injected snippets by stripping out comment prefixes or other unwanted characters.

Check out this example

Using Templates

The template attribute allows you to wrap your snippet with a given template. This is useful when you have a snippet that you want to format in a specific way, such as wrapping it with a YAML tag format.

Check out this example

Executing Snippet Content

The execute action option allows you to execute a snippet as a shell command and collect the output of the command into a snippet. This is useful when you want to add the result of a --help command to your documentation, ensuring that your documentation stays up-to-date with your CLI tool’s output, even if it changes.

Check out this example

Managing Snippets

To manage all snippets effectively, run:

snipdoc show

Creating a YAML File

You can mix snippets from your code with a YAML file configuration. Create an empty snipdoc.yml file by running:

Create an snipdoc.yml file by running the command:

snipdoc create-db --empty

Checking Snippets

Validate that all snippets are valid and match the current injected versions. This is useful for CI workflows to ensure documentation accuracy and consistency.

snipdoc check

Github Action

To integrate Snipdoc with GitHub Actions, use the following workflow configuration:

name: docs

jobs:
  check:
    name: Check
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout the code
        uses: actions/checkout@v4
      - uses: actions-rs/toolchain@v1
        with:
          profile: minimal
          toolchain: stable
          override: true
      - run: cargo install snipdoc        
      - run: snipdoc check        

Modules

cli

A module for handling command line exits with custom messages and exit codes.

config

This module provides configuration management for the snipdoc. It includes functionality to load and manage configurations from a default YAML file.

db

errors

A module for defining custom error types and result aliases for parsing

parser

reporters

walk

This module provides functionality for traversing directories and collecting files, while respecting include and exclude patterns.