Metadata-Version: 2.4
Name: rstformat
Version: 0.1.0
Summary: A formatter for reStructuredText files with plugin support for embedded code blocks
Project-URL: Homepage, https://github.com/lextudio/rstformat
Project-URL: Repository, https://github.com/lextudio/rstformat
Project-URL: Documentation, https://github.com/lextudio/rstformat/blob/master/DESIGN.md
Project-URL: Changelog, https://github.com/lextudio/rstformat/blob/master/CHANGES.rst
Project-URL: Issues, https://github.com/lextudio/rstformat/issues
Author-email: "LeXtudio Inc." <support@lextudio.com>
License: MIT
License-File: LICENSE
Keywords: code-style,docutils,formatter,linter,reStructuredText,rst,sphinx
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.9
Requires-Dist: tomli>=1.2; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: editorconfig
Requires-Dist: editorconfig>=0.12.4; extra == 'editorconfig'
Provides-Extra: lint
Requires-Dist: docutils>=0.21; extra == 'lint'
Requires-Dist: rstcheck>=6.2.0; extra == 'lint'
Description-Content-Type: text/markdown

# rstformat

A formatter for reStructuredText files.

[![Become a Sponsor](https://img.shields.io/badge/Become%20a%20Sponsor-lextudio-orange.svg?style=for-readme)](https://github.com/sponsors/lextudio)
[![PyPI](https://img.shields.io/pypi/v/rstformat.svg)](https://pypi.python.org/pypi/rstformat)
[![PyPI Downloads](https://img.shields.io/pypi/dd/rstformat)](https://pypi.python.org/pypi/rstformat/)
[![Python Versions](https://img.shields.io/pypi/pyversions/rstformat.svg)](https://pypi.python.org/pypi/rstformat/)
[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/lextudio/rstformat/master/LICENSE)

An open source and free formatter for reStructuredText (`.rst`) files, distributed under the MIT License.

## Features

| Feature | Setting |
| ------- | ------- |
| Trim trailing whitespace | `trim_trailing_whitespace` |
| Output line ending (LF / CRLF / auto-detect) | `line_ending` |
| Resize section adornments to title width | `normalize_section_underlines` |
| Add/remove blank lines around headings | `normalize_section_spacing` |
| Limit consecutive blank lines | `max_consecutive_blank_lines` |
| Insert final newline | `insert_final_newline` |
| East-Asian double-width character support | (implicit) |

**Plugin system** for delegating embedded code-block formatting to language-specific tools:

- Python code blocks → **Black** or **Ruff** formatter
- Shell script blocks → **shfmt** formatter
- SQL blocks → **sqlfluff** formatter (planned)

## Installation

Install from PyPI:

```bash
pip install rstformat
```

Or with `uv`:

```bash
uv tool install rstformat
```

To enable optional features:

```bash
pip install rstformat[editorconfig]  # Honor .editorconfig settings
pip install rstformat[lint]          # Pre-flight validation via docutils/rstcheck
pip install rstformat[dev]           # Development dependencies (tests, ruff)
```

## Usage

Format files in-place:

```bash
rstformat file.rst dir/
```

Check mode (exit 1 if any file would change):

```bash
rstformat --check file.rst
```

Show unified diff without writing:

```bash
rstformat --diff file.rst
```

Read from stdin, write to stdout:

```bash
echo "Title\n=====" | rstformat
```

Control output line endings:

```bash
rstformat --line-ending crlf file.rst    # Force Windows (CRLF)
rstformat --line-ending auto file.rst    # Preserve input style
```

For all options, run:

```bash
rstformat --help
```

## Configuration

Create `pyproject.toml` or `.rstfmt.toml` in your project:

```toml
[tool.rstformat]
adornments            = "#*=-^\"'`:.~_+"
insert_final_newline  = true
line_ending           = "lf"   # "lf" | "crlf" | "auto"
max_consecutive_blank_lines = 2
normalize_section_spacing   = true
normalize_section_underlines = true
trim_trailing_whitespace     = true
```

rstformat also respects `.editorconfig` for compatible settings:

```ini
[*.rst]
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
```

For more details, see [DESIGN.md](https://github.com/lextudio/rstformat/blob/master/DESIGN.md).

## Documentation

- [Design & Architecture](./DESIGN.md) — formatting algorithm, extension API, roadmap
- [Changelog](./CHANGES.rst) — version history
- [Security Policy](./SECURITY.md) — supported versions, reporting vulnerabilities
- [Development Notes](./AGENTS.md) — for contributors and AI agents

## License

Copyright (c) 2026 LeXtudio Inc.

Licensed under the MIT License. See [LICENSE](./LICENSE) for details.

## Community

- **GitHub Issues**: [Report bugs or request features](https://github.com/lextudio/rstformat/issues)
- **GitHub Discussions**: [Ask questions](https://github.com/lextudio/rstformat/discussions)
- **Sponsor**: [Support development](https://github.com/sponsors/lextudio)
