🦀doksnet

CI ReadyFastSecure

A Rust CLI tool for documentation ↔ code mapping verification. Create lightweight symbolic links between documentation sections and code snippets, then verify that both sides stay synchronized using cryptographic hashes.

🚀Installation

From crates.io (Recommended)

cargo install doksnet

From GitHub Releases

Download pre-built binaries from GitHub Releases:

  • Linux: doksnet-linux-amd64
  • Windows: doksnet-windows-amd64.exe
  • macOS: doksnet-macos-amd64 (Intel) or doksnet-macos-arm64 (Apple Silicon)

From Source (Development)

git clone https://github.com/Pulko/doksnet
cd doksnet
cargo install --path .

📋Commands Overview

CommandPurposeInteractiveCI/CD Safe
newInitialize a .doks fileYesNo
addCreate doc↔code mappingsYesNo
edit <id>Edit specific mappingYesNo
remove-failedRemove all failed mappingsYesNo
testVerify all mappingsNoYes
test-interactiveTest with guided fixingYesNo

🛠Usage Guide

1. Initialize Project

# Create .doks file in current directory
doksnet new
# Create .doks file in specific directory  
doksnet new /path/to/project

What it does:

  • Scans for documentation files (README.md, etc.)
  • Prompts you to select default documentation file
  • Creates .doks configuration file

2. Create Documentation-Code Mappings

doksnet add

Interactive flow:

  1. Documentation partition: README.md:15-25 or README.md:10-20@5-30
  2. Content preview: Shows extracted documentation text
  3. Confirmation: Verify the selection is correct
  4. Code partition: src/lib.rs:45-60 or src/main.rs:10-25@10-50
  5. Content preview: Shows extracted code text
  6. Confirmation: Verify the selection is correct
  7. Description: Optional description for the mapping
  8. Hash generation: Creates Blake3 hashes and saves mapping

3. Edit Existing Mappings

# Edit by ID (first 8 characters sufficient)
doksnet edit a1b2c3d4

What you can edit:

  • Documentation partition reference
  • Code partition reference
  • Description
  • Both partitions at once

Features:

  • Shows current values
  • Pre-fills input with existing values
  • Previews new content before applying
  • Updates hashes automatically

4. Test Mappings (CI/CD)

# Non-interactive testing for automation
doksnet test

Output:

  • ✅ PASS: Content matches stored hashes
  • ❌ FAIL: Content has changed
  • Exit code 1 if any mappings fail (perfect for CI/CD)

🚀GitHub Action

Doksnet provides a ready-to-use GitHub Action for seamless CI/CD integration:

Basic Usage

name: Documentation Sync Check
on: [push, pull_request]
jobs:
  verify-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Pulko/doksnet@v1
        # Uses defaults: command='test', fail-on-error=true

Advanced Configuration

- uses: Pulko/doksnet@v1
  with:
    command: 'test'           # Command to run
    version: 'latest'         # Doksnet version  
    working-directory: '.'    # Directory to run in
    fail-on-error: true       # Fail workflow on issues

Action Inputs

InputDescriptionDefaultOptions
commandDoksnet command to runtesttest, remove-failed
versionDoksnet version to uselatestlatest, 0.2.0, etc.
working-directoryDirectory to run doksnet in.Any valid path
fail-on-errorFail workflow if issues foundtruetrue, false

Benefits

  • ✅ Zero setup - No need to install Rust/Cargo
  • ⚡ Fast - Cached dependencies, optimized for CI
  • 🔧 Flexible - Configurable commands and error handling
  • 🌍 Cross-platform - Works on Linux, Windows, macOS

Common Patterns

Enforce Documentation Sync:
- uses: Pulko/doksnet@v1
  # Fails CI if docs are out of sync

📄Partition Format

Partitions use this lightweight format to reference file ranges:

<relative_path>:<start_line>-<end_line>@<start_col>-<end_col>

Examples:

  • README.md - Entire file
  • README.md:10-20 - Lines 10-20
  • README.md:15 - Single line 15
  • src/lib.rs:10-20@5-30 - Lines 10-20, columns 5-30
  • docs/guide.md:1-5@1-50 - First 5 lines, first 50 characters

Notes:

  • Line numbers are 1-indexed
  • Column numbers are 1-indexed
  • Ranges are inclusive
  • Non-contiguous ranges require multiple mappings

🎯Use Cases

API Documentation

Link examples in README to actual implementation

Tutorial Sync

Ensure code samples in guides match working code

Architecture Docs

Connect design decisions to code structures

Code Reviews

Verify documentation updates accompany code changes

Legacy Code

Track which docs describe which code sections

Team Collaboration

Maintain consistency across large projects

Built with ❤️ in Rust • Lightweight • Fast • Reliable

crates.ioGitHub