docformatter is a command-line utility that automatically reformats Python docstrings according to the conventions described in PEP 257. It helps maintain consistent documentation formatting across Python projects without requiring developers to edit individual docstrings manually.
Python docstrings describe modules, classes, functions and methods. Although they are embedded directly in source code, their formatting can vary considerably between contributors. Inconsistent indentation, excessive whitespace and poorly wrapped descriptions can make documentation harder to read and maintain.
docformatter addresses these problems by analysing docstrings and applying consistent formatting rules. It concentrates on documentation strings rather than reformatting the surrounding Python statements, making it a useful companion to general-purpose code formatters such as Black.
The utility can be incorporated into development workflows, allowing documentation formatting to be checked automatically before changes are committed. Its configurable behaviour also accommodates projects with different documentation conventions.
This is free and open source software.
Key Features
- Automatic formatting of Python docstrings according to a subset of PEP 257 conventions.
- Normalises triple quotation marks, indentation, whitespace and summary formatting.
- Configurable line wrapping for docstring summaries and longer descriptions.
- Ensures appropriate separation between summary lines and extended descriptions.
- Supports formatting parameter lists written using Sphinx and Epytext conventions.
- Black-compatible formatting option for maintaining consistency with Black-formatted source code.
- In-place formatting for modifying Python source files directly.
- Check mode for identifying files containing incorrectly formatted docstrings without modifying them.
- Diff output showing proposed formatting changes.
- Recursive directory processing with configurable file and directory exclusions.
- Selective formatting based on source line ranges or docstring lengths.
- Configuration support through pyproject.toml and other supported configuration files.
- Integration with pre-commit hooks, GitHub Actions and PyCharm file watchers.
- Options for controlling summary capitalisation, blank lines and quotation mark placement.
- Cross-platform support – runs on Linux and macOS.
Website: github.com/PyCQA/docformatter
Support:
Developer: Steven Myint and PyCQA contributors
License: MIT License
docformatter is written in Python. Learn Python with our recommended free books and free tutorials.
Related Software
| Python Code Formatters | |
|---|---|
| Ruff | Extremely fast Python linter and code formatter |
| YAPF | Python formatter based on clang-format |
| Black | Uncompromising Python code formatter |
| isort | Python utility and library to sort imports |
| autopep8 | Formats Python code to conform to the PEP 8 style guide |
| Darker | Apply black reformatting to Python files |
| Pyink | Python code formatter |
| blue | Somewhat less uncompromising code formatter than black |
| μsort | Sorts import statements |
| eradicate | Remove commented-out code from Python files |
Read our verdict in the software roundup.
 LinuxLinks helps you discover the best free and open source software for Linux. Explore our extensive collection of recommended applications, including alternatives to popular proprietary software.We also publish software reviews, Linux tutorials, hardware reviews, free programming books and articles covering the wider open source community. Browse our Linux resources to discover more. Know a useful free and open source Linux application we haven't covered? Suggest a program for inclusion. Has your software been featured on LinuxLinks? Display one of our Featured on LinuxLinks badges on your website or GitHub README. |
Please read our Comment Policy before commenting.