.. _configuration:

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.

.. code-block:: toml
   :caption: 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.

.. code-block:: toml
   :caption: pyproject.toml

   [tool.g_docformatter]
   indent_size = 4


.. _configuration-paragraph:

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.

.. code-block:: toml
   :caption: 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 :ref:`text formatter <configuration-text-formatters>`
to use. The table below describes the available paragraph types and their options.

.. list-table:: Paragraph types
   :header-rows: 1
   :widths: 20 20 20 40

   * - 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.


.. _configuration-text-formatters:

Text Formatters
---------------

The following text formatters are available:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - 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 :func:`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 <https://black.readthedocs.io>`_ code formatter.
       See :ref:`configuration-black-options` for additional options.


.. _configuration-black-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 :class:`black.Mode` (excluding ``line_length``,
which is derived from the ``width`` and ``indent_size`` settings).

.. code-block:: toml
   :caption: pyproject.toml

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

Refer to the `Black documentation <https://black.readthedocs.io/en/stable/the_black_code_style/index.html>`_
for a full list of supported :class:`black.Mode` options.