Consider merging command line flags and configuration file options descriptions

[mkniewallner]

Description for command line flags and configuration file options are today split across 2 different documentations (here for CLI flags, and here for options).

Despite the options mostly behaving the same whether they are defined through the CLI or a configuration file, most of the descriptions differ (for instance, here for --python-version vs. here for python_version). Additionally to the differences, it also requires to maintain documentation across 2 different places, and may make it harder for people to refer to specific options of mypy.

I'm not sure how feasible this would be, as some options may only be defined in configuration files (especially for module-tied ones), but maybe the "common" options could be merged into a single documentation?

While I think it is auto-generated from the code, isort documentation is a good example of a centralized documentation for options. For each option, both the CLI flags and configuration file option are specified, and examples for each possible configuration type is provided.

[KotlinIsland]

YES! one million times yes. The current documentation for each section has diverged.

I would say scrap the full lists of different options, and just have a 'Options' section, then two sub sections for cli/config file that only contain their specifics, like how the inline config currently is.

[Zeckie]

Could there also be links (both ways) between those and the documentation of the different error codes that are affected by the configuration options (eg. between --disallow-any-generics, disallow_any_generics and type-arg). In this example, there is also the "Generics" section of the documentation.

Some of those links are already there, some are not there yet.

[KotlinIsland]

@Zeckie Maybe raise a separate issue for that.

[wyattscarpenter]

This seems very doable. Based on the three erroneous instances of the word "flag" on the config file page, the people are already yearning to merge these pages.

I may be able to get to this soon, and therefore do it, but I'll wait for some other open documentation PRs to close first to simplify my life.

[wyattscarpenter]

I think this documentation should also be single-sourced and large parts of it should be automatically generated. Besides the inherent limitations of man, the one thing stopping me is that I don't know where precisely the hook for this would go. Somewhere in pre-commit, maybe?