Various documentation updates (#5043)

JukkaL · web-flow · commit 4e25c6779506 · 2018-05-15T09:36:53.000-04:00
This includes a bunch of updates to the documentation, including
(but not limited to) these:

* Remove or update some obsolete things
* Make the ordering within some sections more logical
* Clarify some explanations
* Add some cross references and links
diff --git a/docs/source/basics.rst b/docs/source/basics.rst
@@ -46,30 +46,29 @@ Arguments with default values can be annotated as follows:
    def greeting(name: str, prefix: str = 'Mr.') -> str:
       return 'Hello, {} {}'.format(name, prefix)
 
-Mixing dynamic and static typing
-********************************
+Running mypy
+************
 
-Mixing dynamic and static typing within a single file is often
-useful. For example, if you are migrating existing Python code to
-static typing, it may be easiest to do this incrementally, such as by
-migrating a few functions at a time. Also, when prototyping a new
-feature, you may decide to first implement the relevant code using
-dynamic typing and only add type signatures later, when the code is
-more stable.
+You can type check a program by using the ``mypy`` tool, which is
+basically a linter -- it checks your program for errors without actually
+running it::
 
-.. code-block:: python
+   $ mypy program.py
 
-   def f():
-       1 + 'x'  # No static type error (dynamically typed)
+All errors reported by mypy are essentially warnings that you are free
+to ignore, if you so wish.
 
-   def g() -> None:
-       1 + 'x'  # Type check error (statically typed)
+The next chapter explains how to download and install mypy:
+:ref:`getting-started`.
+
+More command line options are documented in :ref:`command-line`.
 
 .. note::
 
-   The earlier stages of mypy, known as the semantic analysis, may
-   report errors even for dynamically typed functions. However, you
-   should not rely on this, as this may change in the future.
+   Depending on how mypy is configured, you may have to run mypy like
+   this::
+
+     $ python3 -m mypy program.py
 
 The typing module
 *****************
@@ -87,37 +86,33 @@ them (we'll explain ``Iterable`` later in this document):
            print('Hello, {}'.format(name))
 
 For brevity, we often omit the ``typing`` import in code examples, but
-you should always include it in modules that contain statically typed
-code.
-
-The presence or absence of the ``typing`` module does not affect
-whether your code is type checked; it is only required when you use
-one or more special features it defines.
+mypy will give an error if you use definitions such as ``Iterable``
+without first importing them.
 
-Type checking programs
-**********************
-
-You can type check a program by using the ``mypy`` tool, which is
-basically a linter -- it checks your program for errors without actually
-running it::
+Mixing dynamic and static typing
+********************************
 
-   $ mypy program.py
+Mixing dynamic and static typing within a single file is often
+useful. For example, if you are migrating existing Python code to
+static typing, it may be easiest to do this incrementally, such as by
+migrating a few functions at a time. Also, when prototyping a new
+feature, you may decide to first implement the relevant code using
+dynamic typing and only add type signatures later, when the code is
+more stable.
 
-All errors reported by mypy are essentially warnings that you are free
-to ignore, if you so wish.
+.. code-block:: python
 
-The next chapter explains how to download and install mypy:
-:ref:`getting-started`.
+   def f():
+       1 + 'x'  # No static type error (dynamically typed)
 
-More command line options are documented in :ref:`command-line`.
+   def g() -> None:
+       1 + 'x'  # Type check error (statically typed)
 
 .. note::
 
-   Depending on how mypy is configured, you may have to explicitly use
-   the Python 3 interpreter to run mypy. The mypy tool is an ordinary
-   mypy (and so also Python) program. For example::
-
-     $ python3 -m mypy program.py
+   The earlier stages of mypy, known as the semantic analysis, may
+   report errors even for dynamically typed functions. However, you
+   should not rely on this, as this may change in the future.
 
 .. _library-stubs:
 
@@ -147,7 +142,7 @@ the builtins contains a definition like this for ``chr``:
 
     def chr(code: int) -> str: ...
 
-In stub files we don't care about the function bodies, so we use 
+In stub files we don't care about the function bodies, so we use
 an ellipsis instead.  That ``...`` is three literal dots!
 
 Mypy complains if it can't find a stub (or a real module) for a
@@ -175,7 +170,7 @@ typeshed yet).
 
 That's it! Now you can access the module in mypy programs and type check
 code that uses the library. If you write a stub for a library module,
-consider making it available for other programmers that use mypy 
+consider making it available for other programmers that use mypy
 by contributing it back to the typeshed repo.
 
 There is more information about creating stubs in the
diff --git a/docs/source/builtin_types.rst b/docs/source/builtin_types.rst
@@ -3,25 +3,26 @@ Built-in types
 
 These are examples of some of the most common built-in types:
 
-=================== ===============================
-Type                Description
-=================== ===============================
-``int``             integer of arbitrary size
-``float``           floating point number
-``bool``            boolean value
-``str``             unicode string
-``bytes``           8-bit string
-``object``          an arbitrary object (``object`` is the common base class)
-``List[str]``       list of ``str`` objects
-``Tuple[int, int]`` tuple of two ``int`` objects (``Tuple[()]`` is the empty tuple)
-``Tuple[int, ...]`` tuple of an arbitrary number of ``int`` objects
-``Dict[str, int]``  dictionary from ``str`` keys to ``int`` values
-``Iterable[int]``   iterable object containing ints
-``Sequence[bool]``  sequence of booleans
-``Any``             dynamically typed value with an arbitrary type
-=================== ===============================
+====================== ===============================
+Type                   Description
+====================== ===============================
+``int``                integer
+``float``              floating point number
+``bool``               boolean value
+``str``                string (unicode)
+``bytes``              8-bit string
+``object``             an arbitrary object (``object`` is the common base class)
+``List[str]``          list of ``str`` objects
+``Tuple[int, int]``    tuple of two ``int`` objects (``Tuple[()]`` is the empty tuple)
+``Tuple[int, ...]``    tuple of an arbitrary number of ``int`` objects
+``Dict[str, int]``     dictionary from ``str`` keys to ``int`` values
+``Iterable[int]``      iterable object containing ints
+``Sequence[bool]``     sequence of booleans (read-only)
+``Mapping[str, int]``  mapping from ``str`` keys to ``int`` values (read-only)
+``Any``                dynamically typed value with an arbitrary type
+====================== ===============================
 
-The type ``Any`` and type constructors ``List``, ``Dict``,
+The type ``Any`` and type constructors such as ``List``, ``Dict``,
 ``Iterable`` and ``Sequence`` are defined in the ``typing`` module.
 
 The type ``Dict`` is a *generic* class, signified by type arguments within
@@ -30,7 +31,7 @@ strings and and ``Dict[Any, Any]`` is a dictionary of dynamically typed
 (arbitrary) values and keys. ``List`` is another generic class. ``Dict`` and
 ``List`` are aliases for the built-ins ``dict`` and ``list``, respectively.
 
-``Iterable`` and ``Sequence`` are generic abstract base classes that
+``Iterable``, ``Sequence``, and ``Mapping`` are generic types that
 correspond to Python protocols. For example, a ``str`` object or a
 ``List[str]`` object is valid
 when ``Iterable[str]`` or ``Sequence[str]`` is expected. Note that even though
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -6,20 +6,22 @@ Getting started
 Installation
 ************
 
-Mypy requires Python 3.4 or later.  Once you've `installed Python 3 <https://www.python.org/downloads/>`_,
+Mypy requires Python 3.4 or later to run.  Once you've
+`installed Python 3 <https://www.python.org/downloads/>`_,
 you can install mypy with:
 
 .. code-block:: text
 
     $ python3 -m pip install mypy
 
-Note that ``mypy`` itself requires Python 3, but you can still check Python 2
-code using ``mypy`` as discussed in :ref:`python2`.
+Note that even though you need Python 3 to run ``mypy``, type checking
+Python 2 code is fully supported, as discussed in :ref:`python2`.
 
 Installing from source
 **********************
 
-To install mypy from source, clone the github repository and then run
+To install mypy from source, clone the
+`mypy repository on GitHub <https://github.com/python/mypy>`_ and then run
 ``pip install`` locally:
 
 .. code-block:: text
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,7 +6,7 @@
 Welcome to Mypy documentation!
 ==============================
 
-Mypy is a static type checker for Python.
+Mypy is a static type checker for Python 3 and Python 2.7.
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
@@ -1,30 +1,33 @@
 Introduction
 ============
 
-Mypy is a static type checker for Python. If you sprinkle your code
-with type annotations, mypy can type check your code and find common bugs.
-As mypy is a static analyzer, or a lint-like tool, your code's type
-annotations are just hints and don't interfere when running your program.
+Mypy is a static type checker for Python 3 and Python 2.7. If you sprinkle
+your code with type annotations, mypy can type check your code and find common
+bugs. As mypy is a static analyzer, or a lint-like tool, the type
+annotations are just hints for mypy and don't interfere when running your program.
 You run your program with a standard Python interpreter, and the annotations
-are treated primarily as comments.
+are treated effectively as comments.
 
-Using the Python 3 function annotation syntax (using the PEP 484 notation) or
+Using the Python 3 function annotation syntax (using the
+`PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ notation) or
 a comment-based annotation syntax for Python 2 code, you will be able to
 efficiently annotate your code and use mypy to check the code for common
-errors. Mypy has a powerful, easy-to-use, type system with modern features
-such as type inference, generics, function types, tuple types and
+errors. Mypy has a powerful and easy-to-use type system with modern features
+such as type inference, generics, function types, tuple types, and
 union types.
 
 As a developer, you decide how to use mypy in your workflow. You can always
 escape to dynamic typing as mypy's approach to static typing doesn't restrict
 what you can do in your programs. Using mypy will make your programs easier to
-debug, maintain, and understand.
+understand, debug, and maintain.
 
 This documentation provides a short introduction to mypy. It will help you
 get started writing statically typed code. Knowledge of Python and a
 statically typed object-oriented language, such as Java, are assumed.
 
 .. note::
 
-   Mypy is still experimental. There will be changes
-   that break backward compatibility.
+   Mypy is used in production by many companies and projects, but mypy is
+   officially beta software. There will be occasional changes
+   that break backward compatibility. The mypy development team tries to
+   minimize the impact of changes to user code.
diff --git a/docs/source/python2.rst b/docs/source/python2.rst
@@ -89,10 +89,10 @@ function using the form ``# type: (...) -> rt``, where ``rt`` is the
 return type. Note that the  return type annotation contains literal
 three dots.
 
-Note that when using multi-line comments, you do not need to prefix the
+When using multi-line comments, you do not need to prefix the
 types of your ``*arg`` and ``**kwarg`` parameters with ``*`` or ``**``.
 For example, here is how you would annotate the first example using
-multi-line comments.
+multi-line comments:
 
 .. code-block:: python
 
@@ -120,10 +120,11 @@ Additional notes
 - The annotation can be on the same line as the function header or on
   the following line.
 
-- The type syntax for variables is the same as for Python 3.
+- Variables use a comment-based type syntax (explained in
+  :ref:`explicit-var-types`).
 
 - You don't need to use string literal escapes for forward references
-  within comments.
+  within comments (string literal escapes are explained later).
 
 - Mypy uses a separate set of library stub files in `typeshed
   <https://github.com/python/typeshed>`_ for Python 2. Library support
diff --git a/docs/source/type_inference_and_annotations.rst b/docs/source/type_inference_and_annotations.rst
