Not to be confused with rustfmt.
Highly experimental and unstable. Do not depend on this yet.
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.
# 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>...
# 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
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)