rstformat 0.1.0

A formatter for reStructuredText files with plugin support for embedded code blocks

rstformat

A formatter for reStructuredText files.

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:

pip install rstformat

Or with uv:

uv tool install rstformat

To enable optional features:

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:

rstformat file.rst dir/

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

rstformat --check file.rst

Show unified diff without writing:

rstformat --diff file.rst

Read from stdin, write to stdout:

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

Control output line endings:

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

For all options, run:

rstformat --help

Configuration

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

[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:

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

For more details, see DESIGN.md.

Documentation

• Design & Architecture — formatting algorithm, extension API, roadmap
• Changelog — version history
• Security Policy — supported versions, reporting vulnerabilities
• Development Notes — for contributors and AI agents

License

Copyright (c) 2026 LeXtudio Inc.

Licensed under the MIT License. See LICENSE for details.

Community

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions
• Sponsor: Support development