Metadata-Version: 2.4
Name: rstbuddy
Version: 0.2.2
Summary: A tool for ensuring your strucuredText files are (more) syntactically correct
Author-email: Chris Malek <cmalek@caltech.edu>
Maintainer-email: Chris Malek <cmalek@caltech.edu>
Project-URL: Respository, https://github.com/caltechads/rstbuddy
Project-URL: Documentation, https://rstbuddy.readthedocs.io
Project-URL: Issues, https://github.com/caltechads/rstbuddy/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: AUTHORS.txt
Requires-Dist: click>=8.1.7
Requires-Dist: rich>=13.8.1
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pydantic-settings>=2.5.2
Requires-Dist: build>=1.2.2.post1
Requires-Dist: openai>=1.99.6
Requires-Dist: mdformat>=0.7.22
Dynamic: license-file

# 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

```bash
# Install
pip install rstbuddy

# With uv
uv tool -p 3.13 install rstbuddy
```

### Usage

```bash
# 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](https://rstbuddy.readthedocs.org).
