Update config file doc to match command line doc and --help (#7776)

This pull request reorganizes the command line docs, the config file docs, and
the output of `--help` so they all list the options in the same order and all
use the same section heading titles.

It also adds a few previously undocumented flags to the docs, such as `--pretty`
and several of the report generation flags.

As a part of this cleanup, this PR also makes two minor changes to the flags
themselves: `--custom-typing` was renamed to `--custom-typing-module` and
the `--strict-optional-whitelist` flag was deprecated.

Fixes #7574, #7575, #7772.

Author: jolaf

docs/source/command_line.rst

@@ -44,6 +44,18 @@ for full details, see :ref:`running-mypy`.
     Asks mypy to type check the provided string as a program.
 
 
+Optional arguments
+******************
+
+``-h`` / ``--help``
+    Show help message and exit.
+
+``-v`` / ``--verbose``
+    More verbose messages.
+
+``-V`` / ``--version``
+    Show program's version number and exit.
+
 .. _config-file-flag:
 
 Config file
@@ -87,7 +99,7 @@ imports.
     module search path -- this is primarily set from the source files
     passed on the command line, the ``MYPYPATH`` environment variable,
     and the :ref:`mypy_path config option
-    <config-file-import-discovery-global>`.
+    <config-file-import-discovery>`.
 
     Note that this only affects import discovery -- for modules and
     packages explicitly passed on the command line, mypy still
@@ -192,6 +204,7 @@ For more information on how to use these flags, see :ref:`version_and_platform_c
     compile-time constants that are always false.  This flag may
     be repeated.
 
+
 .. _disallow-dynamic-typing:
 
 Disallow dynamic typing
@@ -247,6 +260,7 @@ The following options are available:
     the base class even though that may not actually be the case.  This
     flag makes mypy raise an error instead.
 
+
 .. _untyped-definitions-and-calls:
 
 Untyped definitions and calls
@@ -280,6 +294,7 @@ definitions or calls.
     This flag reports an error whenever a function with type annotations
     is decorated with a decorator without annotations.
 
+
 .. _none-and-optional-handling:
 
 None and Optional handling
@@ -317,11 +332,11 @@ For more details, see :ref:`no_strict_optional`.
     generally check the use of ``None`` values -- they are valid
     everywhere. See :ref:`no_strict_optional` for more about this feature.
 
-.. note::
-    Strict optional checking was enabled by default starting in
+    **Note:** Strict optional checking was enabled by default starting in
     mypy 0.600, and in previous versions it had to be explicitly enabled
     using ``--strict-optional`` (which is still accepted).
 
+
 .. _configuring-warnings:
 
 Configuring warnings
@@ -469,6 +484,7 @@ of the above sections.
     Note: the exact list of flags enabled by running ``--strict`` may change
     over time.
 
+
 .. _configuring-error-messages:
 
 Configuring error messages
@@ -511,6 +527,10 @@ in error messages.
 
     See :ref:`error-codes` for more information.
 
+``--pretty``
+    Use visually nicer output in error messages: use soft word wrap,
+    show source code snippets, and show error location markers.
+
 ``--no-color-output``
     This flag will disable color output in error messages, enabled by default.
 
@@ -519,6 +539,10 @@ in error messages.
     including total number of errors, number of files with errors, and number
     of files checked.
 
+``--show-absolute-path``
+    Show absolute paths to files.
+
+
 .. _incremental:
 
 Incremental mode
@@ -556,14 +580,22 @@ beyond what incremental mode can offer, try running mypy in
     writing to the cache, use ``--cache-dir=/dev/null`` (UNIX)
     or ``--cache-dir=nul`` (Windows).
 
+``--sqlite-cache``
+    Use an `SQLite`_ database to store the cache.
+
+``--cache-fine-grained``
+    Include fine-grained dependency information in the cache for the mypy daemon.
+
 ``--skip-version-check``
     By default, mypy will ignore cache data generated by a different
     version of mypy. This flag disables that behavior.
 
-.. _advanced-flags:
+``--skip-cache-mtime-checks``
+    Skip cache internal consistency checks based on mtime.
+
 
-Advanced flags
-**************
+Advanced options
+****************
 
 The following flags are useful mostly for people who are interested
 in developing or debugging mypy internals.
@@ -576,7 +608,10 @@ in developing or debugging mypy internals.
     If set, this flag will display a full traceback when mypy
     encounters a fatal error.
 
-``--custom-typing MODULE``
+``--raise-exceptions``
+    Raise exception on fatal error.
+
+``--custom-typing-module MODULE``
     This flag lets you use a custom module as a substitute for the
     :py:mod:`typing` module.
 
@@ -622,6 +657,7 @@ in developing or debugging mypy internals.
     cause mypy to type check the contents of ``temp.py`` instead of  ``original.py``,
     but error messages will still reference ``original.py``.
 
+
 Report generation
 *****************
 
@@ -632,6 +668,16 @@ format into the specified directory.
     Causes mypy to generate a text file report documenting how many
     expressions of type ``Any`` are present within your codebase.
 
+``--cobertura-xml-report DIR``
+    Causes mypy to generate a Cobertura XML type checking coverage report.
+
+    You must install the `lxml`_ library to generate this report.
+
+``--html-report`` / ``--xslt-html-report DIR``
+    Causes mypy to generate an HTML type checking coverage report.
+
+    You must install the `lxml`_ library to generate this report.
+
 ``--linecount-report DIR``
     Causes mypy to generate a text file report documenting the functions
     and lines that are typed and untyped within your codebase.
@@ -641,30 +687,29 @@ format into the specified directory.
     absolute filename to a list of line numbers that belong to typed
     functions in that file.
 
-``--cobertura-xml-report DIR``
-    Causes mypy to generate a Cobertura XML type checking coverage report.
+``--lineprecision-report DIR``
+    Causes mypy to generate a flat text file report with per-module
+    statistics of how many lines are typechecked etc.
+
+``--txt-report`` / ``--xslt-txt-report DIR``
+    Causes mypy to generate a text file type checking coverage report.
 
     You must install the `lxml`_ library to generate this report.
 
-``--html-report DIR``, ``--xslt-html-report DIR``
-    Causes mypy to generate an HTML type checking coverage report.
+``--xml-report DIR``
+    Causes mypy to generate an XML type checking coverage report.
 
     You must install the `lxml`_ library to generate this report.
 
-``--txt-report DIR``, ``--xslt-txt-report DIR``
-    Causes mypy to generate a text file type checking coverage report.
 
-    You must install the `lxml`_ library to generate this report.
+Miscellaneous
+*************
 
 ``--junit-xml JUNIT_XML``
     Causes mypy to generate a JUnit XML test result document with
     type checking results. This can make it easier to integrate mypy
     with continuous integration (CI) tools.
 
-
-Miscellaneous
-*************
-
 ``--find-occurrences CLASS.MEMBER``
     This flag will make mypy print out all usages of a class member
     based on static type information. This feature is experimental.
@@ -681,3 +726,4 @@ Miscellaneous
     by this flag is often more convenient.)
 
 .. _lxml: https://pypi.org/project/lxml/
+.. _SQLite: https://www.sqlite.org/