Command line documentation differs from --help

[jolaf]

mypy 0.740

The order in which the command line options are described is different in --help output and in the documentation at https://mypy.readthedocs.io/en/latest/command_line.html, and section names also differ. This inconsistency could be confusing.

Particularly:

• In Import discovery section, --named-packages option goes first in the documentation, but last in --help.
  (FIXED)

• Disallow dynamic typing section in the documentation is named Dynamic typing in --help.
  (FIXED)

• In Disallow dynamic typing section, --disallow-subclassing-any option goes last in the documentation, but second in --help.
  (FIXED)

• --strict-optional-whitelist option is not mentioned in the documentation.
  (FIXED)

• Configuring warnings section in the documentation is named Warnings in --help.
  (FIXED)

• Miscellaneous strictness flags section in the documentation is named Other strictness checks in --help.
  (FIXED)

• In Miscellaneous strictness flags section, --strict-equality option goes after --no-implicit-reexport option in the documentation, but before it in --help.
  (FIXED)

• Configuring error messages goes after Miscellaneous strictness flags section in the documentation, but after Mypy internals in --help.
  (FIXED)

• Configuring error messages in the documentation is named Error reporting in --help.
  (FIXED)

• --pretty option is not mentioned in the documentation.
  (FIXED)

• --sqlite-cache, --cache-fine-grained, --skip-cache-mtime-checks are not mentioned in the documentation.
  (FIXED)

• Advanced flags section in the documentation is named Mypy internals in --help.
  (FIXED)

• --raise-exceptions option is not mentioned in the documentation.
  (FIXED)

• In Report generation section the order of options is different in the documentation and in --help.
  (FIXED)

• --junit-xml belongs to section Report generation in the documentation, but to section Miscellaneous in --help.
  (FIXED)

• --lineprecision-report, --memory-xml-report, --xml-report options are not mentioned in the documentation.
  (FIXED, requires followup after Some Report generation options are undocumented #7775 is resolved)

• In Miscellaneous section, --scripts-are-modules option goes before --find-occurrences in the documentation, but after it in --help.
  (FIXED)

• --verbose, --version options are not mentioned in the documentation.
  (FIXED)

[ilevkivskyi]

Although this doesn't look urgent, it would make sense to keep these more in sync.

[gvanrossum]

A PR would be welcome.

[jolaf]

It's unclear, which source of information (Command line doc, Config file doc, --help) is primary, meaning, is best supported and has the best structure according to the authors.

If one source is updated to reflect the most complete and well structured information, reflecting this information and structure in two other sources would be rather easy.

[gvanrossum]

I would start by making command line docs and config file docs match up better, and then make --help follow the command line docs.

Note there are some necessary differences between command line and config file that need to remain separate, since only the config file supports per-module options; only the command line has --strict (and maybe there are other differences).

@Michael0x2a

[jolaf]

By the way I would suggest removing the separation of options to "Per-module and global" and "Global only" options in the config file doc. Per my opinion this separation makes the document worse:

• It makes options that are similar in their function, to be documented in different places.

• It makes harder updating and synchronizing information on config file and command line options, and harder to find answers on questions like "I know how to do it via command line option, can I do it via a config file?".

• It's hard for me to imagine a person who first thinks about "Do I need it globally or per-module?" and THEN thinks "What exactly do I need"? I think in most cases the person thinks the other way around.

So it seems better to group the config file options in a way similar to the structure of Command line doc, and add notes to the particular options, like "This option can only be configured globally".

[gvanrossum]

Yes. I proposed that in the past but we never acted on it.

[jolaf]

By the way I would suggest removing the separation of options to "Per-module and global" and "Global only" options in the config file doc.

Fixed in #7776.

[jolaf]

Fixed in #7776.