Reorganize command line documentation and related code

This commit reorganizes our documentation about the command line
along with several miscellaneous fixes.

In short, I moved the stuff about running mypy/managing imports
to a separate file, reorganized the command line section, and
tweaked the output of `mypy --help`.

Specific major changes include:

1.  I split up information about running mypy and information
    about mypy's command line flags into two separate pages:
    "Running mypy and managing imports" and "The mypy command line".

    Rationale: I felt the current documentation on running mypy
    is very dense: it includes a lot of info on managing imports, how
    mypy discovers files, etc that I think were really only of interest
    to advanced programmers who are in the middle of trying to get mypy
    to run on a complex code base.

    I think splitting up the text into two makes it easier for
    both beginners and experts to get the info they're looking for.

2.  I rewrote the section about how mypy handles the
    `--ignore-missing-imports` and `--follow-imports` flags
    (Now located in "Running mypy..." > "How mypy handles imports").

    In particular, it more clearly distinguishes how to handle missing
    imports vs handling imports to files you didn't want type check:
    the former is applicable to everybody; the latter is only really
    applicable to people who are progressively adding type hints.

3.  I moved information about how mypy searches the file system and
    resolves imports to the bottom of the "Running mypy..." section.

    I think most people don't really need that info to start:
    running `mypy my_whole_codebase` is generally a good starting point.

4.  I reorganized the command line section to mirror how the flags
    are grouped when you run `mypy --help`.

Some minor changes:

1.  I switched to using [definition lists][0] instead of bullet points
    to document flags: I think it looks cleaner.

2.  I removed the `mypy --help` summary from the command line page:
    I don't really think anybody was reading that at all.

3.  Similarly, I changed `mypy/main.py` to remove that long summary.
    It now has a brief "getting started" message along with links to
    the docs.

4.  I added documentations about the `--warn-unused-casts`,
    `-warn-unused-ignores`, `--show-error-contexts`,
    `--warn-unsed-configs`, and the different report flags.

    I did *not* document `--cache-fine-grained` and
    `--memory-xml-report` mostly because I don't actually understand
    what exactly does do.

5.  I reorganized the flags in `mypy --help` slightly.

  [0]: https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/lists_tables.html#definition-lists

Author: Michael0x2a

docs/source/command_line.rst

@@ -0,0 +1,52 @@
+.. _extending-mypy:
+
+Extending and integrating mypy
+==============================
+
+.. _integrating-mypy:
+
+Integrating mypy into another Python application
+************************************************
+
+It is possible to integrate mypy into another Python 3 application by
+importing ``mypy.api`` and calling the ``run`` function with a parameter of type ``List[str]``, containing
+what normally would have been the command line arguments to mypy.
+
+Function ``run`` returns a ``Tuple[str, str, int]``, namely
+``(<normal_report>, <error_report>, <exit_status>)``, in which ``<normal_report>``
+is what mypy normally writes to ``sys.stdout``, ``<error_report>`` is what mypy
+normally writes to ``sys.stderr`` and ``exit_status`` is the exit status mypy normally
+returns to the operating system.
+
+A trivial example of using the api is the following
+
+.. code-block:: python
+
+    import sys
+    from mypy import api
+
+    result = api.run(sys.argv[1:])
+
+    if result[0]:
+        print('\nType checking report:\n')
+        print(result[0])  # stdout
+
+    if result[1]:
+        print('\nError report:\n')
+        print(result[1])  # stderr
+
+    print ('\nExit status:', result[2])
+
+Extending mypy using plugins
+****************************
+
+Mypy supports a plugin system that lets you customize the way mypy type checks
+code. This can be useful if you want to extend mypy so it can type check code
+that uses a library that is difficult to express using just PEP 484 types, for
+example.
+
+*Warning:* The plugin system is extremely experimental and prone to change. If you want
+to contribute a plugin to mypy, we recommend you start by contacting the mypy
+core developers either on `gitter <https://gitter.im/python/typing>`_ or on mypy's
+`issue tracker <https://github.com/python/mypy/issues>`_.
+

docs/source/extending_mypy.rst

@@ -1,3 +1,5 @@
+.. _getting-started:
+
 Getting started
 ===============
 

docs/source/getting_started.rst

@@ -45,10 +45,12 @@ Mypy is a static type checker for Python 3 and Python 2.7.
    :maxdepth: 2
    :caption: Configuring and running mypy
 
+   running_mypy
    command_line
    config_file
    mypy_daemon
    installed_packages
+   extending_mypy
 
 .. toctree::
    :maxdepth: 2

docs/source/index.rst

@@ -537,7 +537,7 @@ argument list ``index: Union[int, slice]`` and a return type of
 ``Union[T, Sequence[T]]``. If there are no annotations on the
 implementation, then the body is not type checked. If you want to
 force mypy to check the body anyways, use the ``--check-untyped-defs``
-flag (:ref:`more details here <additional-command-line-flags>`).
+flag (:ref:`more details here <untyped-definitions-and-calls-flags>`).
 
 The variants must also also be compatible with the implementation
 type hints. In the ``MyList`` example, mypy will check that the

docs/source/more_types.rst

@@ -173,7 +173,7 @@ detailed release notes):
 
     * Add :ref:`cheat-sheet-py3`.
 
-    * Major update to :ref:`finding-imports`.
+    * Major update to :ref:`mapping-modules-to-paths`.
 
     * Add :ref:`--ignore-missing-imports <ignore-missing-imports>`.