doc-utils

Python CLI tools for maintaining clean, consistent AsciiDoc documentation repositories.

📚 View Full Documentation | 📦 PyPI Package | 🐙 GitHub

⚠️ Safety First

These tools can modify or delete files. Always:

Work in a git branch (never main/master)
Review changes with git diff
Test documentation builds after changes

🚀 Quick Start

Install with pipx (Recommended)

# Install
pipx install rolfedh-doc-utils

# Verify installation
doc-utils --version

# Upgrade to latest version
pipx upgrade rolfedh-doc-utils

Alternative Installation

# With pip user flag
pip install --user rolfedh-doc-utils

# For development
git clone https://github.com/rolfedh/doc-utils.git
cd doc-utils
pip install -e .

🛠️ Available Tools

Quick Reference

Run doc-utils to see all available tools and their descriptions:

doc-utils --help     # Show comprehensive help
doc-utils --list     # List all tools
doc-utils --version  # Show version

Individual Tools

Note: Commands use hyphens (-), while Python files use underscores (_). After installing with pipx, use the hyphenated commands directly.

Tool	Description	Usage
`validate-links`	Validates links in AsciiDoc source files, with URL transposition for preview environments	`validate-links --transpose "https://prod--https://preview"`
`check-published-links`	Validates links on published HTML docs using linkchecker, with URL rewriting for misresolved paths	`check-published-links https://docs.example.com/guide/`
`extract-link-attributes`	Extracts link/xref macros with attributes into reusable definitions	`extract-link-attributes --dry-run`
`replace-link-attributes`	Resolves Vale LinkAttribute issues by replacing attributes in link URLs	`replace-link-attributes --dry-run`
`format-asciidoc-spacing`	Standardizes spacing after headings and around includes	`format-asciidoc-spacing --dry-run modules/`
`check-scannability`	Analyzes readability (sentence/paragraph length)	`check-scannability --max-words 25`
`archive-unused-files`	Finds and archives unreferenced .adoc files	`archive-unused-files` (preview) `archive-unused-files --archive` (execute)
`archive-unused-images`	Finds and archives unreferenced images	`archive-unused-images` (preview) `archive-unused-images --archive` (execute)
`find-unused-attributes`	Identifies unused attribute definitions	`find-unused-attributes attributes.adoc`
`inventory-conditionals`	Creates inventory of `ifdef`/`ifndef` conditionals	`inventory-conditionals ~/docs -o ~/reports/`
`convert-callouts-to-deflist`	Converts callout-style annotations to definition list format	`convert-callouts-to-deflist --dry-run modules/`

📖 Documentation

Comprehensive documentation is available at rolfedh.github.io/doc-utils

OpenShift-docs Example

For OpenShift documentation repositories:

# Format spacing in specific directories
format-asciidoc-spacing modules/
format-asciidoc-spacing microshift_networking/

# Preview changes first
format-asciidoc-spacing --dry-run modules/networking/

# Process specific file
format-asciidoc-spacing modules/networking/about-networking.adoc

💡 Common Workflows

Clean Up Documentation

# 1. Create a branch
git checkout -b doc-cleanup

# 2. Preview what would change
format-asciidoc-spacing --dry-run .
archive-unused-files
archive-unused-images

# 3. Apply changes
format-asciidoc-spacing .
archive-unused-files --archive
archive-unused-images --archive

# 4. Review and commit
git diff
git add -A && git commit -m "Clean up documentation"

Check Documentation Quality

# Check readability
check-scannability --max-words 30 --max-sentences 5

# Find unused attributes
find-unused-attributes attributes.adoc

# Save results
find-unused-attributes attributes.adoc --output unused.txt

🔧 Exclusions

All tools support excluding files and directories:

# Exclude specific directories
archive-unused-files --exclude-dir ./temp --exclude-dir ./drafts

# Exclude specific files
check-scannability --exclude-file ./README.adoc

# Use exclusion list file
echo "./deprecated/" > .docutils-ignore
archive-unused-images --exclude-list .docutils-ignore

🧪 Development

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/ -v

# Run specific test
python -m pytest tests/test_file_utils.py

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Before submitting PRs:

✅ All tests pass
✅ Code follows PEP 8
✅ Documentation updated
✅ Changelog entry added

📊 Project Status

Latest Version: 0.1.16 (with automatic update notifications)
Python Support: 3.8+
Test Coverage: 112+ tests (100% passing)
Dependencies: Minimal (PyYAML for OpenShift-docs support)

🔔 Update Notifications

All tools automatically check for updates and notify you when a new version is available. The notification will recommend the appropriate upgrade command based on how you installed the package:

📦 Update available: 0.1.19 → 0.1.20
   Run: pipx upgrade rolfedh-doc-utils

To disable update checks, set the environment variable:

export DOC_UTILS_NO_VERSION_CHECK=1

Update checks are cached for 24 hours to minimize network requests.

🔗 Resources

📝 License

This project is licensed under the terms specified in the LICENSE file.

Created by Rolfe Dlugy-Hegwer for technical writers everywhere.

Metadata

Release files for rolfedh-doc-utils 0.1.42

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rolfedh-doc-utils 0.1.42
File	Size	Uploaded
rolfedh_doc_utils-0.1.42.tar.gz	130.5 kB	Feb 3, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for rolfedh-doc-utils 0.1.42
File	Interpreter	ABI	Platform	Reset
rolfedh_doc_utils-0.1.42-py3-none-any.whl 135.0 kB Feb 3, 2026	Python 3	none	any	Details

Total release size: 265.6 kB

Release files / rolfedh_doc_utils-0.1.42.tar.gz

Download URL	rolfedh_doc_utils-0.1.42.tar.gz
Size	130.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`f3011818787c5dc7ba867a8227ccf7347f2e17904a8d22f0c1d55ad84ef11243`
BLAKE2b-256 checksum How to use checksums	`c9d836bb8142259fe417fb06ba8358798066650e5a5ffee8004eef680a54ff62`
Upload date	Feb 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.12`

Release files / rolfedh_doc_utils-0.1.42-py3-none-any.whl

Download URL	rolfedh_doc_utils-0.1.42-py3-none-any.whl
Size	135.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`bb4423fd7fc3a0be233895b4397a888dc50b1849335670038165f0b1ffbb606d`
BLAKE2b-256 checksum How to use checksums	`b36e9e4f712ac053b06fd6d725e049a96a902301579db03d94eefc91a276f152`
Upload date	Feb 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.12`