Skip to content

README.md

Latest commit

 

History

History
213 lines (150 loc) · 6.95 KB

README.md

File metadata and controls

213 lines (150 loc) · 6.95 KB

doc-utils

PyPI version Python 3.8+ License Documentation

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.