A formatter for Sphinx flavored reStructuredText.
Project description
Strongly inspired by rstfmt and rustfmt.
This is considered to be in beta however it is mostly stable.
Description
docstrfmt is a tool for automatically formatting reStructuredText in files and Python docstrings in a consistent way.
Like Black and rstfmt, 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, docstrfmt is in an early stage of development. The most common reST constructs are covered but there are some that are not. If there is a construct missing and would like to add it, feel free to open a PR to add it or open an issue and I’ll see what I can do.
To get a feel for the output of docstrfmt, see the sample file.
Differences between docstrfmt and rstfmt
The main difference between rstfmt and docstrfmt is the ability to format Python docstrings. I am open to merging this project with rstfmt, however, there as several differences in formatting conventions between the two (hence the separate fork).
Usage
# Install.
pip install docstrfmt
# Install the development version.
pip install https://github.com/LilSpazJoekp/docstrfmt/archive/master.zip
# Read a file from stdin and write the formatted version to stdout.
docstrfmt
# Format the given file(s) in place.
docstrfmt <file>...
# Format the given files, printing all output to stdout.
docstrfmt -o <file>...
# Wrap paragraphs to the given line length where possible (default to whatever is
# set for black).
docstrfmt -l <length>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 "docstrfmt[d]"
# Install the development version.
pip install "https://github.com/LilSpazJoekp/docstrfmt/archive/master.zip#egg=docstrfmt[d]"
# Start the daemon (binds to localhost:5219 by default).
docstrfmtd --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 to whatever is set for black).
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/stdinWith Editors
PyCharm
Instructions derived from black documentation
Install.
pip install "docstrfmt[d]"Locate where docstrfmt is installed.
On macOS / Linux / BSD:
which docstrfmt # /usr/local/bin/docstrfmt # possible locationOn Windows:
where docstrfmt # C:\Program Files\Python39\Scripts\docstrfmt.exe
Open External tools in PyCharm.
On macOS:
PyCharm -> Preferences -> Tools -> External Tools
On Windows / Linux / BSD:
File -> Settings -> Tools -> External Tools
Click the + icon to add a new external tool with the following values:
Name: docstrfmt
Description:
Program: <install_location_from_step_2>
Arguments: "$FilePath$"
Format the currently opened file by selecting Tools -> External Tools -> docstrfmt.
Alternatively, you can set a keyboard shortcut by navigating to Preferences or Settings -> Keymap -> External Tools -> External Tools - docstrfmt.
Optionally, run docstrfmt on every file save:
Make sure you have the File Watchers plugin installed.
Go to Preferences or Settings -> Tools -> File Watchers and click + to add a new watcher:
Name: docstrfmt
File type: Python
Scope: Project Files
Program: <install_location_from_step_2>
Arguments: $FilePath$
Output paths to refresh: $FilePath$
Working directory: $ProjectFileDir$
Uncheck “Auto-save edited files to trigger the watcher” in Advanced Options
With pre-commit
repos:
- repo: https://github.com/LilSpazJoekp/docstrfmt
rev: stable # Replace by any tag/version: https://github.com/LilSpazJoekp/docstrfmt/tags
hooks:
- id: docstrfmt
language_version: python3
types_or: [python, rst, txt] # only needed if you want to include txt files.Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file docstrfmt-1.9.0.tar.gz.
File metadata
- Download URL: docstrfmt-1.9.0.tar.gz
- Upload date:
- Size: 47.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 03114948588602396f37da7bd54e1fcbd5e7ed8bf535576a03770cc9ba1f58e6 |
|
| MD5 | d32bd491a5899d3305242b29839dd6d8 |
|
| BLAKE2b-256 | 09ee8ada6f5401b8fcf211fce2825a37118c990f165dd0bdb076d0a8e0b34976 |
File details
Details for the file docstrfmt-1.9.0-py3-none-any.whl.
File metadata
- Download URL: docstrfmt-1.9.0-py3-none-any.whl
- Upload date:
- Size: 29.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 27ce689f33b2e8f6d8515214ca1d2b33968f2a212a0a7da73c902bf42017ffc0 |
|
| MD5 | 692f2d378064397c244007c107f2f2ea |
|
| BLAKE2b-256 | 60933ca5782c8f7eb2ec49401a80866ac9e5959f6c17d9889109f83089025c7b |
