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

Reorganize command line documentation #5333

Merged
merged 5 commits into from Aug 3, 2018

Conversation

Projects
None yet
3 participants
@Michael0x2a
Collaborator

Michael0x2a commented Jul 9, 2018

This commit reorganizes our documentation about the command line along with several miscellaneous fixes.

In short, I moved the stuff about running mypy/managing imports to a separate file and reorganized the command line section.

Specific major changes include:

  1. I split up information about running mypy and information about mypy's command line flags into two separate pages: "Running mypy and managing imports" and "The mypy command line".

    Rationale: I felt the current documentation on running mypy is very dense: it includes a lot of info on managing imports, how mypy discovers files, etc that I think were really only of interest to advanced programmers who are in the middle of trying to get mypy to run on a complex code base.

    I think splitting up the text into two makes it easier for both beginners and experts to get the info they're looking for.

  2. I rewrote the section about how mypy handles the --ignore-missing-imports and --follow-imports flags (Now located in "Running mypy..." > "How mypy handles imports").

    In particular, it more clearly distinguishes how to handle missing imports vs handling imports to files you didn't want type check: the former is applicable to everybody; the latter is only really applicable to people who are progressively adding type hints.

  3. I moved information about how mypy searches the file system and resolves imports to the bottom of the "Running mypy..." section.

    I think most people don't really need that info to start: running mypy my_whole_codebase is generally a good starting point.

  4. I reorganized the command line section to mirror how the flags are grouped when you run mypy --help.

Some minor changes:

  1. I switched to using definition lists instead of bullet points to document flags: I think it looks cleaner.

  2. I removed the mypy --help summary from the command line page: I don't really think anybody was reading that at all.

  3. I added documentations about the --warn-unused-casts, -warn-unused-ignores, --show-error-contexts, --warn-unsed-configs, and the different report flags. Those flags were apparently undocumented.

    I did not document --cache-fine-grained and --memory-xml-report mostly because I don't actually understand what exactly those do.

  4. I added moved the note about integrating mypy into a separate page, and added a brief note about plugins to that page.

@Michael0x2a

This comment has been minimized.

Show comment
Hide comment
@Michael0x2a

Michael0x2a Jul 9, 2018

Collaborator

Just for reference, here's what the new sections look like when rendered:

Also, sorry about the size of the diff -- I sort of got carried away. FWIW most of the new stuff is in the "running mypy and managing imports" section -- the diff for the "The mypy command line" page is large, but it's mostly just me re-indenting and lightly tweaking existing text.

Collaborator

Michael0x2a commented Jul 9, 2018

Just for reference, here's what the new sections look like when rendered:

Also, sorry about the size of the diff -- I sort of got carried away. FWIW most of the new stuff is in the "running mypy and managing imports" section -- the diff for the "The mypy command line" page is large, but it's mostly just me re-indenting and lightly tweaking existing text.

@ethanhs

This comment has been minimized.

Show comment
Hide comment
@ethanhs

ethanhs Jul 9, 2018

Collaborator

I think it would make reviewing much easier to separate the mypy --help diff and the docs changes into two separate PRs. (Those seem like two discrete things to me). Is there any reason not to/ would it be possible?

Collaborator

ethanhs commented Jul 9, 2018

I think it would make reviewing much easier to separate the mypy --help diff and the docs changes into two separate PRs. (Those seem like two discrete things to me). Is there any reason not to/ would it be possible?

@Michael0x2a

This comment has been minimized.

Show comment
Hide comment
@Michael0x2a

Michael0x2a Jul 9, 2018

Collaborator

@ethanhs: Yeah, I thought about doing that. The only real issue is that the new --help text includes a link to a new page that this pull request introduces, which is mildly awkward. The actual changes to mypy/main.py were pretty minor though, so I figured I might as well combine the two.

Also, I was hungry and wanted to go get dinner :/

I can look into splitting it up a little later though -- I suppose we can always just wait on merging until both PRs are approved to avoid temporary out-of-sync-ness.

Edit: they're split up now.

Collaborator

Michael0x2a commented Jul 9, 2018

@ethanhs: Yeah, I thought about doing that. The only real issue is that the new --help text includes a link to a new page that this pull request introduces, which is mildly awkward. The actual changes to mypy/main.py were pretty minor though, so I figured I might as well combine the two.

Also, I was hungry and wanted to go get dinner :/

I can look into splitting it up a little later though -- I suppose we can always just wait on merging until both PRs are approved to avoid temporary out-of-sync-ness.

Edit: they're split up now.

Reorganize command line documentation
This commit reorganizes our documentation about the command line
along with several miscellaneous fixes.

In short, I moved the stuff about running mypy/managing imports
to a separate file and reorganized the command line section.

Specific major changes include:

1.  I split up information about running mypy and information
    about mypy's command line flags into two separate pages:
    "Running mypy and managing imports" and "The mypy command line".

    Rationale: I felt the current documentation on running mypy
    is very dense: it includes a lot of info on managing imports, how
    mypy discovers files, etc that I think were really only of interest
    to advanced programmers who are in the middle of trying to get mypy
    to run on a complex code base.

    I think splitting up the text into two makes it easier for
    both beginners and experts to get the info they're looking for.

2.  I rewrote the section about how mypy handles the
    `--ignore-missing-imports` and `--follow-imports` flags
    (Now located in "Running mypy..." > "How mypy handles imports").

    In particular, it more clearly distinguishes how to handle missing
    imports vs handling imports to files you didn't want type check:
    the former is applicable to everybody; the latter is only really
    applicable to people who are progressively adding type hints.

3.  I moved information about how mypy searches the file system and
    resolves imports to the bottom of the "Running mypy..." section.

    I think most people don't really need that info to start:
    running `mypy my_whole_codebase` is generally a good starting point.

4.  I reorganized the command line section to mirror how the flags
    are grouped when you run `mypy --help`.

Some minor changes:

1.  I switched to using [definition lists][0] instead of bullet points
    to document flags: I think it looks cleaner.

2.  I removed the `mypy --help` summary from the command line page:
    I don't really think anybody was reading that at all.

3.  I added documentations about the `--warn-unused-casts`,
    `-warn-unused-ignores`, `--show-error-contexts`,
    `--warn-unsed-configs`, and the different report flags.

    I did *not* document `--cache-fine-grained` and
    `--memory-xml-report` mostly because I don't actually understand
    what exactly those do.

4.  I added moved the note about integrating mypy into a separate
    page, and added a brief note about plugins to that page.

  [0]: https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/lists_tables.html#definition-lists

@Michael0x2a Michael0x2a changed the title from Reorganize command line documentation and related code to Reorganize command line documentation Jul 9, 2018

Michael0x2a added a commit to Michael0x2a/mypy that referenced this pull request Jul 9, 2018

Adjust output of --help text to mirror command line changes
This commit adjusts the output of running `mypy --help` to mirror the
changes made in python#5333.

Specifically, it rearranges the order of the flags slightly and replaces
the summary of the flags at the top with a short description of how to
use mypy along with links for learning more.

gvanrossum added some commits Aug 3, 2018

Add disallow-incomplete-defs label
Needed after merge with master.
@gvanrossum

Looks great! I fixed a few nits. Once tests pass I'll merge.

@gvanrossum gvanrossum merged commit 3c9ee34 into python:master Aug 3, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@gvanrossum

This comment has been minimized.

Show comment
Hide comment
@gvanrossum

gvanrossum Aug 3, 2018

Member

Thanks again!

Member

gvanrossum commented Aug 3, 2018

Thanks again!

Michael0x2a added a commit that referenced this pull request Aug 4, 2018

Adjust output of --help text to mirror command line changes (#5334)
This commit adjusts the output of running `mypy --help` to mirror the
changes made in #5333.

Specifically, it rearranges the order of the flags slightly and replaces
the summary of the flags at the top with a short description of how to
use mypy along with links for learning more.

It also makes every group title and flag help text start with a capital.

@Michael0x2a Michael0x2a deleted the Michael0x2a:reorganize-command-line-docs branch Aug 27, 2018

@Michael0x2a Michael0x2a referenced this pull request Sep 16, 2018

Closed

Release 0.630 planning #5537

9 of 12 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment