jdillard / rstfmt

A formatter for reStructuredText

rstfmt: a formatter for reStructuredText

Not to be confused with rustfmt.

Highly experimental and unstable. Do not depend on this yet.

Description

rstfmt is a tool for automatically formatting reStructuredText files in a consistent way.

Like Black and gofmt, the motivation is to provide a format that is reasonable and minimally configurable to prevent teams from wasting time on style discussions (or individuals on manually doing formatting, for that matter).

Currently, rstfmt is in a very early stage of development. Not all reST constructs are covered and the interface or formatting may change at any time without warning.

To get a feel for the output of rstfmt, see the sample file.

Usage

# Install directly from the repository.
pip install git+https://github.com/dzhu/rstfmt

# Install from PyPI.
pip install rstfmt

# Read a file from stdin and write the formatted version to stdout.
rstfmt

# Exit with a nonzero status code if any files are not formatted.
rstfmt --check <file>...

# Format the given files in place.
rstfmt <file>...

# Format all files with the `rst` or `txt` extension inside a directory.
rstfmt <directory>...
rstfmt --ext txt <directory>...

# Wrap paragraphs to the given line length (default 72).
rstfmt -w <width>

Like Black's blackd, there is also a daemon that provides formatting via HTTP requests to avoid the cost of starting and importing everything on every run.

# Install.
pip install 'git+https://github.com/dzhu/rstfmt#egg=rstfmt[d]'
pip install 'rstfmt[d]'

# Start the daemon (binds to localhost:5219 by default).
rstfmtd --bind-host=<host> --bind-port=<port>

# Print the formatted version of a file.
curl http://locahost:5219 --data-binary @<file>

# Specify the line length (default 72).
curl -H 'X-Line-Length: 72' http://locahost:5219 --data-binary @<file>

# Mimic the standalone tool: read from stdin, write to stdout, exit with
# a nonzero status code if there are errors.
curl -fsS http://locahost:5219 --data-binary @/dev/stdin

With editors

The default behavior of reading from stdin and writing to stdout should integrate well with other systems, such as on-save hooks in editors. For example, here's a configuration for reformatter.el, including both standalone and daemon modes:

;; Run the standalone tool.
(reformatter-define rstfmt
  :program "rstfmt")
(add-hook 'rst-mode-hook #'rstfmt-on-save-mode)

;; Query the daemon.
(reformatter-define client-rstfmt
  :program "curl"
  :args '("-fsS" "http://localhost:5219" "--data-binary" "@/dev/stdin"))
(add-hook 'rst-mode-hook #'client-rstfmt-on-save-mode)