8000 Consider merging command line flags and configuration file options descriptions · Issue #12347 · python/mypy · GitHub
[go: up one dir, main page]
Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
mkniewallner opened this issue Mar 14, 2022 · 5 comments
Open

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

mkniewallner opened this issue Mar 14, 2022 · 5 comments
Labels
documentation

Comments

@mkniewallner
Copy link
Contributor

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
Copy link
Contributor
KotlinIsland commented Mar 17, 2022 •
edited
Loading

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
Copy link
Zeckie commented Mar 17, 2022

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
Copy link
Contributor

@Zeckie Maybe raise a separate issue for that.

@hauntsaninja hauntsaninja mentioned this issue Nov 12, 2023
Open
@wyattscarpenter
Copy link
Contributor

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
Copy link
Contributor
wyattscarpenter commented May 17, 2025 •
edited
Loading

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@mkniewallner @wyattscarpenter @Zeckie @KotlinIsland
0