Start documenting configuration parsing

docs/source/internal/option_handling.rst

@@ -117,7 +117,64 @@ extra arguments we highlighted above.
 Configuration File Management
 -----------------------------
 
-.. todo:: Add notes about Config File Management
+In Flake8 2, configuration file discovery and management was handled by pep8.
+In pep8's 1.6 release series, it drastically broke how discovery and merging
+worked (as a result of trying to improve it). To avoid a dependency breaking
+Flake8 again in the future, we have created our own discovery and management.
+As part of managing this ourselves, we decided to change management/discovery
+for 3.0.0. We have done the following:
+
+- User files (files stored in a user's home directory or in the XDG directory
+  inside their home directory) are the first files read. For example, if the
+  user has a ``~/.flake8`` file, we will read that first.
+
+- Project files (files stored in the current directory) are read next and
+  merged on top of the user file. In other words, configuration in project
+  files takes precedence over configuration in user files.
+
+- **New in 3.0.0** The user can specify ``--append-config <path-to-file>``
+  repeatedly to include extra configuration files that should be read and
+  take precedence over user and project files.
+
+- **New in 3.0.0** The user can specify ``--config <path-to-file>`` to so this
+  file is the only configuration file used. This is a change from Flake8 2
+  where pep8 would simply merge this configuration file into the configuration
+  generated by user and project files (where this takes precedence).
+
+- **New in 3.0.0** The user can specify ``--isolated`` to disable
+  configuration via discovered configuration files.
+
+To facilitate the configuration file management, we've taken a different
+approach to discovery and management of files than pep8. In pep8 1.5, 1.6, and
+1.7 configuration discovery and management was centralized in `66 lines of
+very terse python`_ which was confusing and not very explicit. The terseness
+of this function (Flake8's authors believe) caused the confusion and problems
+with pep8's 1.6 series. As such, Flake8 has separated out discovery,
+management, and merging into a module to make reasoning about each of these
+pieces easier and more explicit (as well as easier to test).
+
+Configuration file discovery is managed by the
+:class:`~flake8.options.config.ConfigFileFinder` object. This object needs to
+know information about the program's name, any extra arguments passed to it,
+and any configuration files that should be appended to the list of discovered
+files. It provides methods for finding the files and similiar methods for
+parsing those fles. For example, it provides
+:meth:`~flake8.options.config.ConfigFileFinder.local_config_files` to find
+known local config files (and append the extra configuration files) and it
+also provides :meth:`~flake8.options.config.ConfigFileFinder.local_configs`
+to parse those configuration files.
+
+.. note:: ``local_config_files`` also filters out non-existent files.
+
+Configuration file merging and managemnt is controlled by the
+:class:`~flake8.options.config.MergedConfigParser`. This requires the instance
+of :class:`~flake8.options.manager.OptionManager` that the program is using,
+the list of appended config files, and the list of extra arguments.
+
+.. todo:: Describe how the MergedConfigParser parses and merges config options
+
+.. _66 lines of very terse python:
+    https://github.com/PyCQA/pep8/blob/b8088a2b6bc5b76bece174efad877f764529bc74/pep8.py#L1981..L2047
 
 API Documentation
 -----------------
@@ -129,5 +186,10 @@ API Documentation
     :members:
     :special-members:
 
+.. autoclass:: flake8.options.config.ConfigFileFinder
+    :members:
+    :special-members:
+
 .. autoclass:: flake8.options.config.MergedConfigParser
     :members:
+    :special-members: