Configuration

Google Docformatter reads configuration from the [tool.g_docformatter] section in the pyproject.toml file in the root of your project.

Width

The maximum line width is controlled by the width option. The default value is 88.

pyproject.toml

[tool.g_docformatter]
width = 88

Indent Size

The number of spaces to use for indentation is controlled by the indent_size option. The default value is 4.

pyproject.toml

[tool.g_docformatter]
indent_size = 4

Paragraph Formatting

Each paragraph type in a docstring can be formatted with a different text formatter. The paragraph option is a table of paragraph types, each with their own set of formatting options.

pyproject.toml

[tool.g_docformatter.paragraph.root]
summary = "inverse_hanging_indent"
eod = "indent_only"

[tool.g_docformatter.paragraph.body]
text = "uniform_indent"
repl_code = "indent_only"

[tool.g_docformatter.paragraph.list_section]
header = "indent_only"
list_item = "hanging_indent"

[tool.g_docformatter.paragraph.std_section]
header = "indent_only"

[tool.g_docformatter.paragraph.sphinx_code_block]
header = "indent_only"
option = "indent_only"
"code.default" = "as_is"
"code.python" = "black"

The value for each option is the name of a text formatter to use. The table below describes the available paragraph types and their options.

Paragraph types

Section	Option	Default	Description
root	summary	inverse_hanging_indent	Text formatter for the summary line of the docstring.
root	eod	indent_only	Text formatter for the end-of-docstring closing quotes.
body	text	uniform_indent	Text formatter for body description text.
body	repl_code	indent_only	Text formatter for REPL (interactive Python session) code blocks in the body.
list_section	header	indent_only	Text formatter for the section header of list-style sections (e.g. Args:, Returns:).
list_section	list_item	hanging_indent	Text formatter for individual items within list-style sections.
std_section	header	indent_only	Text formatter for the section header of standard text sections (e.g. Note:, Warning:).
sphinx_code_block	header	indent_only	Text formatter for the .. code-block:: directive header.
sphinx_code_block	option	indent_only	Text formatter for options within a .. code-block:: directive.
sphinx_code_block	code.default	as_is	Text formatter for code blocks with no recognised language.
sphinx_code_block	code.python	black	Text formatter for Python code blocks.

Text Formatters

The following text formatters are available:

Name	Description
as_is	Returns the text unchanged. Useful for preserving manually formatted content.
indent_only	Applies the correct indentation without reflowing or wrapping the text.
uniform_indent	Reflows the text using textwrap.fill() with uniform indentation on all lines.
hanging_indent	Reflows the text so the first line is at the current indent level and subsequent lines are indented one level further.
inverse_hanging_indent	Reflows the text so the first line has no indentation and subsequent lines are indented at the current indent level.
black	Formats Python code using the Black code formatter. See Black Formatter Options for additional options.

Black Formatter Options

Options for the Black text formatter can be passed via the text_formatter_options.black table. These are forwarded directly to black.Mode (excluding line_length, which is derived from the width and indent_size settings).

pyproject.toml

[tool.g_docformatter.text_formatter_options.black]
target_versions = ["py311", "py312"]

Refer to the Black documentation for a full list of supported black.Mode options.