Skip to content

Commit 79a0a18

Browse files
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-lists
1 parent 219fbf8 commit 79a0a18

File tree

6 files changed

+830
-440
lines changed

6 files changed

+830
-440
lines changed

0 commit comments

Comments
 (0)