[mypyc] Various documentation updates (#9098)

Includes many changes (this list is not exhaustive):

* Document how to pass mypy options.
* Document some additional primitives.
* Protocols are now supported.
* General wordsmithing.

Author: JukkaL

mypyc/doc/dict_operations.rst

@@ -33,12 +33,16 @@ Statements
 ----------
 
 * ``d[key] = value``
+* ``for key in d:``
 
 Methods
 -------
 
 * ``d.get(key)``
 * ``d.get(key, default)``
+* ``d.keys()``
+* ``d.values()``
+* ``d.items()``
 * ``d1.update(d2: dict)``
 * ``d.update(x: Iterable)``
 

mypyc/doc/differences_from_python.rst

@@ -262,12 +262,6 @@ Descriptors
 Native classes can't contain arbitrary descriptors. Properties, static
 methods and class methods are supported.
 
-Defining protocols
-******************
-
-Protocols can't be defined in compiled code. You can use protocols
-defined elsewhere, however.
-
 Stack introspection
 *******************
 

mypyc/doc/getting_started.rst

@@ -50,10 +50,10 @@ On some systems you need to use this instead:
 
     $ python -m pip install -U mypy
 
-Compile and run a program
--------------------------
+Example program
+---------------
 
-Let's now compile a classic micro-benchmark, recursive fibonacci. Save
+Let's start with a classic micro-benchmark, recursive fibonacci. Save
 this file as ``fib.py``:
 
 .. code-block:: python
@@ -70,8 +70,8 @@ this file as ``fib.py``:
    fib(32)
    print(time.time() - t0)
 
-Note that we gave ``fib`` a type annotation. Without it, performance
-won't be as impressive after compilation.
+Note that we gave the ``fib`` function a type annotation. Without it,
+performance won't be as impressive after compilation.
 
 .. note::
 
@@ -81,6 +81,9 @@ won't be as impressive after compilation.
    mypy to perform type checking and type inference, so some familiarity
    with mypy is very useful.
 
+Compiling and running
+---------------------
+
 We can run ``fib.py`` as a regular, interpreted program using CPython:
 
 .. code-block:: console
@@ -114,9 +117,12 @@ After compilation, the program is about 10x faster. Nice!
 
    ``__name__`` in ``fib.py`` would now be ``"fib"``, not ``"__main__"``.
 
+You can also pass most
+`mypy command line options <https://mypy.readthedocs.io/en/stable/command_line.html>`_
+to ``mypyc``.
 
-Delete compiled binary
-----------------------
+Deleting compiled binary
+------------------------
 
 You can manually delete the C extension to get back to an interpreted
 version (this example works on Linux):
@@ -125,11 +131,11 @@ version (this example works on Linux):
 
     $ rm fib.*.so
 
-Compile using setup.py
-----------------------
+Using setup.py
+--------------
 
 You can also use ``setup.py`` to compile modules using mypyc. Here is an
-example::
+example ``setup.py`` file::
 
     from setuptools import setup
 
@@ -154,40 +160,67 @@ Now you can build a wheel (.whl) file for the package::
 
 The wheel is created under ``dist/``.
 
+You can also compile the C extensions in-place, in the current directory (similar
+to using ``mypyc`` to compile modules)::
+
+    python3 setup.py build_ext --inplace
+
+You can include most `mypy command line options
+<https://mypy.readthedocs.io/en/stable/command_line.html>`_ in the
+list of arguments passed to ``mypycify()``. For example, here we use
+the ``--disallow-untyped-defs`` flag to require that all functions
+have type annotations::
+
+    ...
+    setup(
+        name='frobnicate',
+        packages=['frobnicate'],
+        ext_modules=mypycify([
+            '--disallow-untyped-defs',  # Pass a mypy flag
+            'frobnicate.py',
+        ]),
+    )
+
+.. note:
+
+   You may be tempted to use `--check-untyped-defs
+   <https://mypy.readthedocs.io/en/stable/command_line.html#cmdoption-mypy-check-untyped-defs>`_
+   to type check functions without type annotations. Note that this
+   may reduce performance, due to many transitions between type-checked and unchecked
+   code.
+
 Recommended workflow
 --------------------
 
 A simple way to use mypyc is to always compile your code after any
-code changes, but this can get tedious. Instead, you may prefer
-another workflow, where you compile code less often.  The following
-development workflow has worked very well for developing mypy and
-mypyc, and we recommend that you to try it out:
+code changes, but this can get tedious, especially if you have a lot
+of code. Instead, you can do most development in interpreted mode.
+This development workflow has worked smoothly for developing mypy and
+mypyc (often we forget that we aren't working on a vanilla Python
+project):
 
-1. During development, use interpreted mode. This allows a very fast
-   edit-run cycle, since you don't need to wait for mypyc compilation.
+1. During development, use interpreted mode. This gives you a fast
+   edit-run cycle.
 
 2. Use type annotations liberally and use mypy to type check your code
    during development. Mypy and tests can find most errors that would
-   break your compiled version, if you have good annotation
-   coverage. (Running mypy is faster than compiling, and you can run
-   your code even if there are mypy errors.)
+   break your compiled code, if you have good type annotation
+   coverage. (Running mypy is pretty quick.)
 
 3. After you've implemented a feature or a fix, compile your project
-   and run tests again, now in compiled mode. Almost always, nothing
-   will break here, if your type annotation coverage is good
-   enough. This can happen locally or as part of a Continuous
-   Integration (CI) job. If you have good CI, compiling locally may be
-   rarely needed.
+   and run tests again, now in compiled mode. Usually nothing will
+   break here, assuming your type annotation coverage is good. This
+   can happen locally or in a Continuous Integration (CI) job. If you
+   have CI, compiling locally may be rarely needed.
 
 4. Release or deploy a compiled version. Optionally, include a
    fallback interpreted version for platforms that mypyc doesn't
    support.
 
-This way of using mypyc has minimal impact on your productivity and
-requires only minor adjustments to a typical Python workflow. Most of
-development, testing and debugging happens in interpreted
-mode. Incremental mypy runs, especially when using mypy daemon, are
-very quick (often a few hundred milliseconds).
+This mypyc workflow only involves minor tweaks to a typical Python
+workflow. Most of development, testing and debugging happens in
+interpreted mode. Incremental mypy runs, especially when using the
+mypy daemon, are very quick (often a few hundred milliseconds).
 
 Next steps
 ----------