rstbuddy 0.2.1

A tool for ensuring your strucuredText files are (more) syntactically correct

rstbuddy

A Python command-line tool for working with reStructuredText (RST) files. Provides comprehensive link validation, RST file cleaning and fixing, and optional AI-powered summarization capabilities.

Core Features

RST Link Checking

• External HTTP(S) links with concurrent checking and robots.txt support
• Sphinx cross-references (:ref:, :doc:)
• Directive paths (include, literalinclude, download, image, figure, thumbnail)
• Smart scanning that ignores code blocks while preserving admonitions

RST File Cleaning & Fixing

• Markdown to RST conversion (headings, code blocks, inline code)
• Heading normalization and list spacing fixes
• Code block and directive formatting
• Stray Markdown fence removal

AI-Powered Summarization (Optional)

• RST to Markdown conversion using Pandoc
• AI summary generation with OpenAI API
• Requires OpenAI API key configuration

Quick Start

Requirements

• Python 3.11 or later
• Pandoc (optional, for AI summarization)
• OpenAI API key (optional, for AI summarization)

Installation

# Install
pip install rstbuddy

# With uv
uv tool -p 3.13 install rstbuddy

Usage

# Check all links in default doc/source directory
rstbuddy check-links

# Fix formatting issues in an RST file
rstbuddy fix document.rst

# Generate AI summary (requires OpenAI API key)
rstbuddy summarize document.rst

# Show help
rstbuddy --help

Commands

• check-links: Validate external URLs, internal references, and file paths
• fix: Clean and fix RST formatting issues, convert Markdown constructs
• summarize: Generate AI-powered summaries (requires OpenAI API key)
• settings: Display current configuration settings
• version: Display version info for important packages used by rstbuddy (for bug reports)

Common Use Cases

• Documentation Maintenance: Validate links and fix formatting before publishing
• Quality Assurance: Check for broken references and maintain consistent RST formatting
• Content Migration: Convert Markdown to RST and fix common formatting issues

Documentation

For detailed usage, configuration, and troubleshooting, see the full documentation.