Package: docstrfmt
Strongly inspired byrstfmtandrustfmt.This is considered to be in beta however it is mostly stable.Descriptiondocstrfmt is a tool for automatically formattingreStructuredTextin files and Python
docstrings in a consistent way.LikeBlackandrstfmt, 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, seethe sample file.Differences between docstrfmt andrstfmtThe main difference betweenrstfmtand docstrfmt is the ability to format Python
docstrings. I am open to merging this project withrstfmt, however, there as several
differences in formatting conventions between the two (hence the separate fork).Usage# Install.pipinstalldocstrfmt# Install the development version.pipinstallhttps://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 88).docstrfmt-l<length>Like Black’sblackd, there is also a daemon that provides formatting via HTTP requests
to avoid the cost of starting and importing everything on every run.# Install.pipinstall"docstrfmt[d]"# Install the development version.pipinstall"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.curlhttp://locahost:5219--data-binary@<file># Specify the line length (default 88).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-fsShttp://locahost:5219--data-binary@/dev/stdinWith editorsPyCharmInstructions derived fromblack documentationInstall.pipinstall"docstrfmt[d]"Locate wheredocstrfmtis installed.On macOS / Linux / BSD:whichdocstrfmt# /usr/local/bin/docstrfmt  # possible locationOn Windows:wheredocstrfmt# C:\Program Files\Python39\Scripts\docstrfmt.exeNoteNote that if you are using a virtual environment detected by PyCharm, this is an
unneeded step. In this case the path todocstrfmtis$PyInterpreterDirectory$/docstrfmt.Open External tools in PyCharm.On macOS:PyCharm -> Preferences -> Tools -> External ToolsOn Windows / Linux / BSD:File -> Settings -> Tools -> External ToolsClick the + icon to add a new external tool with the following values:Name: docstrfmtDescription:Program: <install_location_from_step_2>Arguments:"$FilePath$"Format the currently opened file by selectingTools -> External Tools -> docstrfmt.Alternatively, you can set a keyboard shortcut by navigating toPreferences or
Settings -> Keymap -> External Tools -> External Tools - docstrfmt.Optionally, rundocstrfmton every file save:Make sure you have theFile Watchersplugin installed.Go toPreferences or Settings -> Tools -> File Watchersand click+to add a
new watcher:Name: docstrfmtFile type: PythonScope: Project FilesProgram: <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 OptionsWith pre-commitrepos:-repo:https://github.com/LilSpazJoekp/docstrfmtrev:stable# Replace by any tag/version: https://github.com/LilSpazJoekp/docstrfmt/tagshooks:-id:docstrfmtlanguage_version:python3types_or:[python,rst,txt]# only needed if you want to include txt files.