Miscellaneous doc updates (python#2460)

JukkaL · web-flow · commit 582a83301a26 · 2016-11-16T14:24:18.000Z
* Document additional command line options

* Improve documentation of using Python 3.6 features

* Document MYPY
diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst
@@ -12,18 +12,20 @@ flag (or its long form ``--help``)::
               [-s] [--almost-silent] [--disallow-untyped-calls]
               [--disallow-untyped-defs] [--check-untyped-defs]
               [--disallow-subclassing-any] [--warn-incomplete-stub]
-              [--warn-redundant-casts] [--warn-unused-ignores]
-              [--hide-error-context] [--fast-parser] [-i] [--cache-dir DIR]
-              [--strict-optional]
-              [--strict-optional-whitelist [GLOB [GLOB ...]]] [--pdb]
-              [--show-traceback] [--stats] [--inferstats]
-              [--custom-typing MODULE] [--custom-typeshed-dir DIR]
-              [--scripts-are-modules] [--config-file CONFIG_FILE]
-              [--show-column-numbers] [--html-report DIR]
-              [--linecount-report DIR] [--linecoverage-report DIR]
-              [--memory-xml-report DIR] [--old-html-report DIR]
-              [--txt-report DIR] [--xml-report DIR] [--xslt-html-report DIR]
-              [--xslt-txt-report DIR] [-m MODULE] [-c PROGRAM_TEXT] [-p PACKAGE]
+              [--warn-redundant-casts] [--warn-no-return]
+              [--warn-unused-ignores] [--hide-error-context] [--fast-parser]
+              [-i] [--cache-dir DIR] [--strict-optional]
+              [--strict-optional-whitelist [GLOB [GLOB ...]]]
+              [--junit-xml JUNIT_XML] [--pdb] [--show-traceback] [--stats]
+              [--inferstats] [--custom-typing MODULE]
+              [--custom-typeshed-dir DIR] [--scripts-are-modules]
+              [--config-file CONFIG_FILE] [--show-column-numbers]
+              [--find-occurrences CLASS.MEMBER] [--cobertura-xml-report DIR]
+              [--html-report DIR] [--linecount-report DIR]
+              [--linecoverage-report DIR] [--memory-xml-report DIR]
+              [--old-html-report DIR] [--txt-report DIR] [--xml-report DIR]
+              [--xslt-html-report DIR] [--xslt-txt-report DIR] [-m MODULE]
+              [-c PROGRAM_TEXT] [-p PACKAGE]
               [files [files ...]]
 
   (etc., too long to show everything here)
@@ -339,7 +341,18 @@ Here are some more useful flags:
   in the current directory.  Settings override mypy's built-in defaults
   and command line flags can override settings.  See :ref:`config-file`
   for the syntax of configuration files.
-  
+
+- ``--junit-xml JUNIT_XML`` will make mypy generate a JUnit XML test
+  result document with type checking results. This can make it easier
+  to integrate mypy with continuous integration (CI) tools.
+
+- ``--find-occurrences CLASS.MEMBER`` will make mypy print out all
+  usages of a class member based on static type information. This
+  feature is experimental.
+
+- ``--cobertura-xml-report DIR`` causes mypy to generate a Cobertura
+  XML type checking coverage report.
+
 For the remaining flags you can read the full ``mypy -h`` output.
 
 .. note::
diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst
@@ -299,7 +299,7 @@ Displaying the type of an expression
 
 You can use ``reveal_type(expr)`` to ask mypy to display the inferred
 static type of an expression. This can be useful when you don't quite
-understand how mypy handles a particlar piece of code. Example:
+understand how mypy handles a particular piece of code. Example:
 
 .. code-block:: python
 
@@ -354,3 +354,19 @@ File ``bar.py``:
 
    The ``TYPE_CHECKING`` constant defined by the ``typing`` module
    is ``False`` at runtime but ``True`` while type checking.
+
+Python 3.5.1 doesn't have ``typing.TYPE_CHECKING``. An alternative is
+to define a constant named ``MYPY`` that has the value ``False``
+at runtime. Mypy considers it to be ``True`` when type checking.
+Here's the above example modified to use ``MYPY``:
+
+.. code-block:: python
+
+   from typing import List
+
+   MYPY = False
+   if MYPY:
+       import bar
+
+   def listify(arg: 'bar.BarClass') -> 'List[bar.BarClass]':
+       return [arg]
diff --git a/docs/source/python36.rst b/docs/source/python36.rst
@@ -11,6 +11,21 @@ support matrix for these in mypy (to be updated with each new mypy
 release).  The intention is to support all of these by the time Python
 3.6 is released.
 
+.. note::
+
+   Mypy only understands Python 3.6 syntax if you use the ``--fast-parser`` flag.
+   This requires that the `typed_ast <https://pypi.python.org/pypi/typed-ast>`_ package is
+   installed and has at least version 0.6.1.  Use ``pip3 install -U typed_ast``.
+   If running mypy on an earlier Python version, you also need to enable 3.6 support
+   through ``--python-version 3.6``.
+
+   Example command line (or use :ref:`config-file`):
+
+     .. code-block:: text
+
+        $ pip3 install -U typed_ast
+        $ mypy --fast-parser --python-version 3.6 program.py
+
 Syntax for variable annotations (`PEP 526 <https://www.python.org/dev/peps/pep-0526>`_)
 ---------------------------------------------------------------------------------------
 
@@ -31,10 +46,7 @@ Mypy fully supports this syntax, interpreting them as equivalent to
 
 .. note::
 
-   This requires the ``--fast-parser`` flag and it requires that the
-   `typed_ast <https://pypi.python.org/pypi/typed-ast>`_ package is
-   installed and has at least version 0.6.1.  Use ``pip3 install -U typed_ast``.
-
+   See above for how to enable Python 3.6 syntax.
 
 Literal string formatting (`PEP 498 <https://www.python.org/dev/peps/pep-0498>`_)
 ---------------------------------------------------------------------------------
