Python Docstring Formatter Extension

Simple extension that implements
docformatter as a native VSCode
formatter. The formatter uses
PEP 257 as a guide.

Features

See https://pypi.org/project/docformatter/ for the full feature list. This
extension uses that project as a backend with few modifications.

All relevant flags are implemented as extension settings.

How to Use

If you already have a Python formatting extension installed, you will need to
pick this one when you want to format a file. In a Python file in VSCode,
ctrl+shift+p to open the command pallette,
run the command Format Document With… and select
Python Docstring Formatter.

To set the default formatter that is run when you run the Format Document,
on Python files, add the following to your settings.json (... being your other settings):

{
    ...,
    "[python]": {
        "editor.defaultFormatter": "iansan5653.format-python-docstrings"
    }
}

Note: The Python Docstring Formatter option will only appear for files
that have been saved on disk (ie, not Untitled-# tabs).

Note: The extension will use the Python you have set in python.pythonPath.
It does not support Python 2, so this must be set to some version of Python 3.
If the setting is empty, the extension will use a global Python installation.

Requirements

This extension requires pip and/or the docformatter module to be installed.
Upon activating, the extension will automatically give the option to run
pip install --upgrade docformatter if necessary. If you prefer to install the
formatter program in another way, you may do so. Just make sure that the
docformatter command is recognized by your terminal (ie, added to your PATH).

Extension Settings

All relevant flags from the original docformatter program are implemented as
settings:

• docstringFormatter.wrapSummariesLength (number, default 79): Wrap long
  summary lines at this length; set to 0 to disable wrapping.
• docstringFormatter.wrapDescriptionsLength (number, default 72): Wrap
  descriptions at this length; set to 0 to disable wrapping.
• docstringFormatter.preSummaryNewline (boolean, default false): Add a
  newline before the summary of a multi-line docstring.
• docstringFormatter.makeSummaryMultiline (boolean, default false): Add a
  newline before and after the summary of a one-line docstring.
• docstringFormatter.forceWrap (boolean, default false): Force
  descriptions to be wrapped even if it may result in a mess.

Release Notes

See CHANGELOG.md for release notes.

Contributing

Before contributing, you will need to install
Node.js (with NPM) (and Visual Studio Code, of course).
Clone the repository and install the required dependencies by running
npm install in a terminal in the new directory. All extension logic is in
src/extension.ts. Whenever modifying extension behavior, be sure to update and
add unit tests in src/test/extension.test.ts. To run/test the extension,
simply use the debugger in VSCode after opening the extension folder.