From 98a60acd191e657a52f2cdb7bfd8cbeb0f22ba12 Mon Sep 17 00:00:00 2001
From: Dimitri Papadopoulos Orfanos
 <3234522+DimitriPapadopoulos@users.noreply.github.com>
Date: Mon, 7 Oct 2024 17:58:53 +0200
Subject: [PATCH] Improve config file documentation in README (#3495)

---
 README.rst | 62 +++++++++++++++++++++++++++---------------------------
 1 file changed, 31 insertions(+), 31 deletions(-)

diff --git a/README.rst b/README.rst
index 6c07a77422..393a950df6 100644
--- a/README.rst
+++ b/README.rst
@@ -161,7 +161,8 @@ Using a config file
 
 Command line options can also be specified in a config file.
 
-When running ``codespell``, it will check in the current directory for a file
+When running ``codespell``, it will check in the current directory for an
+`INI file <https://en.wikipedia.org/wiki/INI_file>`_
 named ``setup.cfg`` or ``.codespellrc`` (or a file specified via ``--config``),
 containing an entry named ``[codespell]``. Each command line argument can
 be specified in this file (without the preceding dashes), for example:
@@ -173,32 +174,16 @@ be specified in this file (without the preceding dashes), for example:
     count =
     quiet-level = 3
 
-The ``.codespellrc`` file is an `INI file <https://en.wikipedia.org/wiki/INI_file>`_,
-which is read using Python's
-`configparser <https://docs.python.org/3/library/configparser.html#supported-ini-file-structure>`_.
-For example, comments are possible using ``;`` or ``#`` as the first character.
-
-Values in an INI file entry cannot start with a ``-`` character, so if you need to do this,
-structure your entries like this:
-
-.. code-block:: ini
-
-    [codespell]
-    dictionary = mydict,-
-    ignore-words = bar,-foo
-
-instead of these invalid entries:
-
-.. code-block:: ini
-
-    [codespell]
-    dictionary = -,mydict
-    ignore-words = -foo,bar
+Python's
+`configparser <https://docs.python.org/3/library/configparser.html#supported-ini-file-structure>`_
+module defines the exact format of INI config files. For example,
+comments are possible using ``;`` or ``#`` as the first character.
 
 Codespell will also check in the current directory for a ``pyproject.toml``
-(or a path can be specified via ``--toml <filename>``) file, and the
-``[tool.codespell]`` entry will be used, but only if the tomli_ package
-is installed for versions of Python prior to 3.11. For example:
+file (or a file specified via ``--toml``), and the ``[tool.codespell]``
+entry will be used. For versions of Python prior to 3.11, this requires
+the tomli_ package. For example, here is the TOML equivalent of the
+previous config file:
 
 .. code-block:: toml
 
@@ -207,25 +192,40 @@ is installed for versions of Python prior to 3.11. For example:
     count = true
     quiet-level = 3
 
-These are both equivalent to running:
+The above INI and TOML files are equivalent to running:
 
 .. code-block:: sh
 
-    codespell --quiet-level 3 --count --skip "*.po,*.ts,./src/3rdParty,./src/Test"
+    codespell --skip "*.po,*.ts,./src/3rdParty,./src/Test" --count --quiet-level 3
 
 If several config files are present, they are read in the following order:
 
-#. ``pyproject.toml`` (only if the ``tomli`` library is available)
+#. ``pyproject.toml`` (only if the ``tomli`` library is available for Python < 3.11)
 #. ``setup.cfg``
 #. ``.codespellrc``
 #. any additional file supplied via ``--config``
 
 If a codespell configuration is supplied in several of these files,
 the configuration from the most recently read file overwrites previously
-specified configurations.
+specified configurations. Any options specified in the command line will
+*override* options from the config files.
 
-Any options specified in the command line will *override* options from the
-config files.
+Values in a config file entry cannot start with a ``-`` character, so if
+you need to do this, structure your entries like this:
+
+.. code-block:: ini
+
+    [codespell]
+    dictionary = mydict,-
+    ignore-words = bar,-foo
+
+instead of these invalid entries:
+
+.. code-block:: ini
+
+    [codespell]
+    dictionary = -,mydict
+    ignore-words = -foo,bar
 
 .. _tomli: https://pypi.org/project/tomli/