Clean up documentation about command line and config file flags #5032
Description
Currently, the documentation for command line flags and the config file flags is a bit disorganized.
Specifically:
-
The information about how mypy finds files should probably be moved somewhere. Right now, the command line page introduces the flags, talks about how files are found, then jumps backs to talking about flags.
This sort of makes sense, because we need to talk about certain command line flags to talk about how files are found, but I can't help but feel there's a cleaner way of doing this.
-
The "Additional command line flags" section could probably be split up.
-
Having the "Integrating mypy into another application" section live within the command line section seems unintuitive, especially for newcomers.
Maybe we could add a new "extending and integrating mypy" top-level page? That could also maybe be a home for documentation about the editor integrations, the api, and the plugin system sometime in the distant future.
-
There's some overlap in information between the pages about command line flags and the config file flags. (There might not be a clean way of getting rid of this redundancy, though).
-
The flags mentioned in the config file page could probably be organized into subsections.
-
It might be nice to briefly mention in mypy's "introduction" page that you can use the command line or config file to customize how strict you want mypy to be? We already talk about how gradual typing gives you one escape hatch; I think the configuration options count as another.
Possible pycon-sprints candidate? Feel free to remove the label if anybody disagrees.