search

python / mypy

Optional static typing for Python
https://www.mypy-lang.org/
Other
18.42k stars 2.82k forks source link

Consider merging command line flags and configuration file options descriptions #12347

Open mkniewallner opened 2 years ago

mkniewallner commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@Zeckie Maybe raise a separate issue for that.