Reorganize command line documentation

[Michael0x2a]

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 and reorganized the command line section.

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 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. I added documentations about the --warn-unused-casts, -warn-unused-ignores, --show-error-contexts, --warn-unsed-configs, and the different report flags. Those flags were apparently undocumented.

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

4. I added moved the note about integrating mypy into a separate page, and added a brief note about plugins to that page.

[Michael0x2a]

Just for reference, here's what the new sections look like when rendered:

• Running mypy and managing imports
• The mypy command line

Also, sorry about the size of the diff -- I sort of got carried away. FWIW most of the new stuff is in the "running mypy and managing imports" section -- the diff for the "The mypy command line" page is large, but it's mostly just me re-indenting and lightly tweaking existing text.

[ethanhs]

I think it would make reviewing much easier to separate the mypy --help diff and the docs changes into two separate PRs. (Those seem like two discrete things to me). Is there any reason not to/ would it be possible?

[Michael0x2a]

@ethanhs: Yeah, I thought about doing that. The only real issue is that the new --help text includes a link to a new page that this pull request introduces, which is mildly awkward. The actual changes to mypy/main.py were pretty minor though, so I figured I might as well combine the two.

Also, I was hungry and wanted to go get dinner :/

I can look into splitting it up a little later though -- I suppose we can always just wait on merging until both PRs are approved to avoid temporary out-of-sync-ness.

Edit: they're split up now.

[gvanrossum]

Looks great! I fixed a few nits. Once tests pass I'll merge.

[gvanrossum]

Thanks again!