Skip to content

Clean up documentation about command line and config file flags #5032

Closed

Description

@Michael0x2a

Currently, the documentation for command line flags and the config file flags is a bit disorganized.

Specifically:

  • The information about how mypy finds files should probably be moved somewhere. Right now, the command line page introduces the flags, talks about how files are found, then jumps backs to talking about flags.

    This sort of makes sense, because we need to talk about certain command line flags to talk about how files are found, but I can't help but feel there's a cleaner way of doing this.

  • The "Additional command line flags" section could probably be split up.

  • Having the "Integrating mypy into another application" section live within the command line section seems unintuitive, especially for newcomers.

    Maybe we could add a new "extending and integrating mypy" top-level page? That could also maybe be a home for documentation about the editor integrations, the api, and the plugin system sometime in the distant future.

  • There's some overlap in information between the pages about command line flags and the config file flags. (There might not be a clean way of getting rid of this redundancy, though).

  • The flags mentioned in the config file page could probably be organized into subsections.

  • It might be nice to briefly mention in mypy's "introduction" page that you can use the command line or config file to customize how strict you want mypy to be? We already talk about how gradual typing gives you one escape hatch; I think the configuration options count as another.

Possible pycon-sprints candidate? Feel free to remove the label if anybody disagrees.

Activity

  1. JukkaL commented on May 14, 2018

    @JukkaL
    Collaborator

    All the ideas sound good! These changes would make things much clearer for new users. This can be implemented using multiple independent PRs, no need to try to solve all the issues at once.

  2. Michael0x2a commented on Dec 26, 2018

    @Michael0x2a
    CollaboratorAuthor

    As an update, I'm closing this PR: the first 5 bullet points with the following PRs:

    The last bullet point is on my mental TODO list/should probably be a separate PR, anyways.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions