-
-
Notifications
You must be signed in to change notification settings - Fork 2.9k
Commit 79a0a18
committed
Reorganize command line documentation
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][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. 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 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.
[0]: https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/lists_tables.html#definition-lists1 parent 219fbf8 commit 79a0a18Copy full SHA for 79a0a18
File tree
6 files changed
+830
-440
lines changedFilter options
- docs/source
6 files changed
+830
-440
lines changed
0 commit comments