Skip to content
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.

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

Reformat and reorganize the config file docs #5595

Merged
merged 3 commits into from Sep 15, 2018

Commits on Sep 11, 2018

  1. Reformat and reorganize the config file docs

    Sorry again for another big docs PR. This time, I'm cleaning 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.
    Michael0x2a committed Sep 11, 2018
    Copy the full SHA
    ca5b60c View commit details
    Browse the repository at this point in the history

Commits on Sep 14, 2018

  1. Respond to code review

    Michael0x2a committed Sep 14, 2018
    Copy the full SHA
    aefb347 View commit details
    Browse the repository at this point in the history

Commits on Sep 15, 2018

  1. Copy the full SHA
    8a7485c View commit details
    Browse the repository at this point in the history