doc-utils

A comprehensive collection of Python utilities and CLI tools designed to help technical writers maintain clean, consistent AsciiDoc documentation repositories.

Get started now View on GitHub

Safety First!

These tools can modify or delete files in your documentation repository. Always:

  • Work in a git branch - Never run these tools on the main/master branch
  • Review all changes carefully - Use git diff or a pull request to verify modifications
  • Check your preview builds - Ensure no documentation errors were introduced

Quick Start

Installation 

# Recommended: Install with pipx
pipx install rolfedh-doc-utils

# Alternative: Install with pip
pip install --user rolfedh-doc-utils

Available Tools

📝 format-asciidoc-spacing

Standardizes AsciiDoc formatting by ensuring proper spacing after headings and around include directives.

Learn More →

🔍 check-scannability

Analyzes document readability by checking sentence and paragraph length against best practices.

Learn More →

🗄️ archive-unused-files

Finds and optionally archives unreferenced AsciiDoc files in your documentation repository.

Learn More →

🖼️ archive-unused-images

Identifies and archives image files that are no longer referenced in your documentation.

Learn More →

🏷️ find-unused-attributes

Scans for AsciiDoc attribute definitions that are declared but never used in your documentation.

Learn More →

Key Features

  • 🚀 Easy Installation - Single package installation via pip or pipx
  • 🔒 Safety First - Built-in safety warnings and dry-run modes
  • 📁 Smart Detection - Automatically detects repository structure (OpenShift-docs or traditional)
  • 🎯 Flexible Exclusions - Exclude specific files or directories from processing
  • 📊 Detailed Reports - Clear output showing what was found and what actions were taken
  • 🐍 Pure Python - Cross-platform compatibility with minimal dependencies

Documentation

Latest Release

Version 0.1.6 - Released September 10, 2025

What’s New

  • ✨ New format-asciidoc-spacing tool for standardizing AsciiDoc formatting
  • 🔧 Automatically adds blank lines after headings and around include directives
  • 📝 Supports dry-run mode and verbose output

View all releases →

Resources