Document --new-semantic-analyzer (#7023)

Author: JukkaL

docs/source/command_line.rst

@@ -622,6 +622,19 @@ Miscellaneous
     have many scripts that import a large package, the behavior enabled
     by this flag is often more convenient.)
 
+``--new-semantic-analyzer``
+    This flag switches to an improved, experimental implementation of
+    the *semantic analyzer* (the part of mypy that binds Python
+    names to definitions). The old and the new semantic analyzers
+    mostly behave identically. The new semantic analyzer is better at
+    handling import cycles and forward references to definitions. It
+    also fixes inconsistencies between the daemon and non-daemon modes,
+    and it detects additional error conditions.
+
+    Likely, the next mypy release will use the new semantic analyzer by
+    default, and the old semantic analyzer will be removed in the next
+    release after that.
+
 .. _PEP 420: https://www.python.org/dev/peps/pep-0420/
 
 .. _PEP 561: https://www.python.org/dev/peps/pep-0561/

docs/source/config_file.rst

@@ -456,3 +456,7 @@ Miscellaneous
 
 ``verbosity`` (integer, default 0)
     Controls how much debug output will be generated.  Higher numbers are more verbose.
+
+``new_semantic_analyzer`` (bool, default False)
+    Enables the experimental new semantic analyzer.
+    (See :ref:`The mypy command line <command-line>` for more information.)