Skip to content

Commit 8e19635

Browse files
authored
Reformat and reorganize the config file docs (#5595)
This PR cleans up the config file docs. Here are a list of notable changes made: 1. I moved the example to come before we list the options, not after. I feel this makes the first section of the page more digestible: we have a big block of text, but at least now we can see some of that information in practice immediately after. 2. I combined the two examples into one (and rewrote the explanations in list form, to help mitigate the increase in complexity). 3. I swapped the global-only and per-module sections. After auditing the options, it seemed to me that the global-only options were generally less useful then the per-module options. I also think it makes sense to present the more flexible options first, rather then last. 4. I organized the options into the same categories I introduced when organizing mypy's command line interface. Thankfully, most categories were entirely per-module or entirely global-only, with a few exceptions. 5. I switched to using the same definition list format we use in the command line docs for consistency. 6. I removed the `dump_type_stats`, `dump_inference_stats`, `debug_cache`, and the `strict_boolean` options. These are all options we have either suppressed or deprecated. 7. I added in documentation for the `python_executable`, `no_site_packages`, and `disallow_untyped_decorators` options. 8. I renamed some links/deleted some now-unnecessary links. One change I made that was unrelated to the config file was adding docs about the `mypy_path` and the per-module `ignore_missing_imports` options to the "Running mypy" page. Some interesting inconsistencies I noticed (but took no action on, in a probably-futile attempt to keep this diff small): 1. The `warn_redundant_casts` section is global-only, not per-module like the other warning options. I left this option in the global misc section for now. 2. There does not appear to be any way of writing a config file that does the same thing as `--no-site-packages`. I think we should either add an option for this or allow expressions like `python_executable = None`. (Currently, we try parsing `None` as a string -- this makes mypy promptly crash with a FileNotFoundError). Final note: I mostly kept the descriptions the same/minimal, apart from some minor wording tweaks here and there -- I wanted to have the command line docs act as the main source of truth.
1 parent a8562c7 commit 8e19635

8 files changed

+349
-195
lines changed

docs/source/command_line.rst

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,8 @@ imports.
126126
compliant packages. Adding this flag will disable this behavior.
127127

128128

129+
.. _platform-configuration:
130+
129131
Platform configuration
130132
**********************
131133

@@ -169,12 +171,15 @@ For more information on how to use these flags, see :ref:`version_and_platform_c
169171
compile-time constants that are always false. This flag may
170172
be repeated.
171173

172-
.. _disallow-any:
174+
.. _disallow-dynamic-typing:
175+
176+
Disallow dynamic typing
177+
***********************
173178

174-
Disallow Any
175-
************
179+
The ``Any`` type is used represent a value that has a :ref:`dynamic type <dynamic-typing>`.
180+
The ``--disallow-any`` family of flags will disallow various uses of the ``Any`` type in
181+
a module -- this lets us strategically disallow the use of dynamic typing in a controlled way.
176182

177-
The ``--disallow-any`` family of flags disallows various types of ``Any`` in a module.
178183
The following options are available:
179184

180185
``--disallow-any-unimported``
@@ -208,8 +213,6 @@ The following options are available:
208213
``dict``) become disallowed as you should use their aliases from the typing
209214
module (such as ``List[int]`` and ``Dict[str, str]``).
210215

211-
.. _disallow-subclassing-any:
212-
213216
``--disallow-subclassing-any``
214217
This flag reports an error whenever a class subclasses a value of
215218
type ``Any``. This may occur when the base class is imported from
@@ -239,8 +242,6 @@ definitions or calls.
239242
This flag reports an error whenever it encounters a function definition
240243
without type annotations.
241244

242-
.. _disallow-incomplete-defs:
243-
244245
``--disallow-incomplete-defs``
245246
This flag reports an error whenever it encounters a partly annotated
246247
function definition.
@@ -258,6 +259,7 @@ definitions or calls.
258259
This flag reports an error whenever a function with type annotations
259260
is decorated with a decorator without annotations.
260261

262+
.. _none-and-optional-handling:
261263

262264
None and Optional handling
263265
**************************
@@ -299,6 +301,7 @@ For more details, see :ref:`no_strict_optional`.
299301
mypy 0.600, and in previous versions it had to be explicitly enabled
300302
using ``--strict-optional`` (which is still accepted).
301303

304+
.. _configuring-warnings:
302305

303306
Configuring warnings
304307
********************
@@ -353,6 +356,8 @@ of the above sections.
353356
Note: the exact list of flags enabled by running ``--strict`` may change
354357
over time.
355358

359+
.. _configuring-error-messages:
360+
356361
Configuring error messages
357362
**************************
358363

@@ -440,6 +445,8 @@ beyond what incremental mode can offer, try running mypy in
440445
We recommend that you try using the :ref:`mypy_daemon` before
441446
attempting to use this feature.
442447

448+
.. _advanced-flags:
449+
443450
Advanced flags
444451
**************
445452

0 commit comments

Comments
 (0)