Quickstart Guide

This guide will get you up and running with rstbuddy quickly, showing the command-line interface for working with reStructuredText (RST) files.

Prerequisites

Python 3.11 or higher
Follow the Installation Guide instructions to install rstbuddy
Pandoc (optional, required only for AI summarization feature)
OpenAI API key (optional, required only for AI summarization feature)

Configuration

Typically the defaults that ship with rstbuddy will work.

You can configure rstbuddy using configuration files or environment variables. See Configuration: Command Line Tool for more details.

Basic Usage

Get Help

# Show main help
rstbuddy --help

# Show help for specific commands
rstbuddy check-links --help
rstbuddy fix --help
rstbuddy summarize --help
rstbuddy settings --help

Check Links Usage

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

# Check links in specific directory
rstbuddy check-links /path/to/docs

# Use custom timeout and workers
rstbuddy check-links --timeout 10 --max-workers 16

# Skip robots.txt checks
rstbuddy check-links --no-check-robots

Fix RST Files Usage

# Fix a single RST file (creates backup automatically)
rstbuddy fix document.rst

# Preview changes without modifying the file
rstbuddy fix document.rst --dry-run

# Fix multiple files at a time
find . -name "*.rst" -exec rstbuddy fix {} \;

AI Summarization Usage

Important

OpenAI API Key Required: This feature requires a valid OpenAI API key. See Configuration: Command Line Tool for setup instructions.

# Generate AI summary of an RST file
rstbuddy summarize document.rst

# Use with custom configuration
rstbuddy --config-file ai-config.toml summarize document.rst

Settings Usage

# Show all current settings
rstbuddy settings

# Show settings in JSON format
rstbuddy --output json settings

# Show settings in text format
rstbuddy --output text settings

Output Formats

# Use table format (default) for human reading
rstbuddy check-links --output table

# Use JSON format for scripting
rstbuddy check-links --output json

# Use text format for simple output
rstbuddy check-links --output text

Next Steps

Now that you have the basics working:

Usage: See Using the Command Line Interface for more advanced features and detailed examples.
Configuration: See Configuration: Command Line Tool for configuration options.
Troubleshooting: See the troubleshooting sections in each guide for common issues.

Getting Help

Check the full documentation for detailed examples
Review the troubleshooting sections in each guide
Report issues on the GitHub repository

Common Workflows

Documentation Maintenance

# 1. Check for broken links
rstbuddy check-links

# 2. Fix formatting issues
rstbuddy fix /path/to/rst_file.rst

# 3. Verify fixes
rstbuddy check-links

Content Migration

# 1. Fix Markdown-to-RST conversion issues
rstbuddy fix migrated_document.rst

# 2. Check that all internal links work
rstbuddy check-links

# 3. Generate summary (if AI features enabled)
rstbuddy summarize migrated_document.rst

Quality Assurance

# 1. Validate all documentation links
rstbuddy check-links /path/to/docs

# 2. Fix any formatting issues
find /path/to/docs -name "*.rst" -exec rstbuddy fix {} \;

# 3. Re-check links to ensure fixes worked
rstbuddy check-links /path/to/docs