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

Documentation updates #13681

Closed
hauntsaninja opened this issue Sep 19, 2022 · 1 comment
Closed

Documentation updates #13681

hauntsaninja opened this issue Sep 19, 2022 · 1 comment

Comments

@hauntsaninja
Copy link
Collaborator

hauntsaninja commented Sep 19, 2022

Since we're starting to plan a 1.0 release, I'm taking the opportunity to do a pass over the mypy docs.

Some overarching goals include:

  • Increase consistency. It's pretty common to see multiple places in the mypy docs where we talk about the same thing in different ways.
  • In particular, the command line and config file reference often diverge in ways that are surprising to users and contributors (we should maybe unify these entirely)
  • Fix up out of date references. In various places, things are slightly out of date in 2022.
  • Make changes with a global view of the docs. Various sections have accreted information over time. Splitting out, reordering and relinking things can make things more accessible to newcomers to the type system and lend a sense of progression as you read through the docs.
  • Make things more accessible. The mypy docs are the best Python type system reference out there, so it's important to make sure we continue to serve newcomers well

I'm not planning on proactively explaining all my changes in each PR, but if you're reviewing them, please feel free to ask why I changed something.

hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Sep 19, 2022
See python#13681

In particular, it's really common to want to make progress towards
`--strict`, and we currently don't really have any guidance on doing so.
Per-module ignore_errors is also a really useful tool for adopting mypy.

Also try to link more to existing documentation elsewhere.
JukkaL pushed a commit that referenced this issue Sep 20, 2022
hauntsaninja added a commit that referenced this issue Sep 20, 2022
See #13681

In particular, it's really common to want to make progress towards
`--strict`, and we currently don't really have any guidance on doing so.
Per-module ignore_errors is also a really useful tool for adopting mypy.
hauntsaninja added a commit that referenced this issue Sep 20, 2022
See #13681

PEP 563 is in limbo, so fix incorrect statements

Mention what type comments are since we've deleted most documentation of
type comments when dropping support for Python 2

The new docs theme underemphasises notes, so maybe warning role is
better
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Sep 26, 2022
See python#13681. I'd like to make bigger changes to this page, but still
thinking them through
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Sep 26, 2022
See python#13681.

Prefer mypy: ignore-errors over module level type: ignore, which is
surprising. Fold starred expr section into talking about PEP 526
declaration only. Don't talk about stubs.
hauntsaninja added a commit that referenced this issue Sep 26, 2022
See #13681. I'd like to make bigger changes to this page, but still
thinking them through
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Sep 26, 2022
See python#13681.

The current documentation page isn't friendly because it's basically an
API reference before we get to the fun bit about typing.Protocol.
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Sep 26, 2022
See python#13681

"Mapping file paths to modules" belongs next to "Specifying code to be
checked". "How imports are found" belongs next to "How mypy handles
imports".
hauntsaninja added a commit that referenced this issue Sep 26, 2022
See #13681.

Prefer mypy: ignore-errors over module level type: ignore, which is
surprising. Fold starred expr section into talking about PEP 526
declaration only. Don't talk about stubs.

Co-authored-by: Jelle Zijlstra <[email protected]>
@hauntsaninja hauntsaninja mentioned this issue Sep 26, 2022
17 tasks
hauntsaninja added a commit that referenced this issue Sep 27, 2022
See #13681

"Mapping file paths to modules" belongs next to "Specifying code to be
checked". "How imports are found" belongs next to "How mypy handles
imports". The "other advice" section was mostly redundant.
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Oct 12, 2022
- Mention PEP 604 unions
- Separate out the 3.8 stuff to keep things readable

Linking python#13681
hauntsaninja added a commit that referenced this issue Oct 18, 2022
- Mention PEP 604 unions
- Separate out the 3.8 stuff to keep things more readable
- Remove mention of typing.Match
- Remove unnecessary mention of stub
- Make classes more prominent
- Clarify that forward references fail at runtime
- More of an example for Any
- Mention None return
- Make default value example mean something
- Move Union docs to builtin types

Linking #13681
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Nov 4, 2022
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Nov 4, 2022
See python#13681

More clearly point out the speed cost and the alternative of installing
stub packages directly
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Feb 1, 2023
For the most part, this shortens the Getting Started page, which was
getting a little too long to read comfortably and had caveats that
aren't super important.

The cheat sheet does a really great job of "show, don't tell", so
recommend that even more aggressively for beginners. The BankAccount
example was nice, and the cheat sheet was missing a discussion on
inheritance, so move a version of that over there.

Finally, most users of mypy don't need to know the details of typeshed
and stub files, especially not when getting started. So reframe as a
more generic section about types for third party libraries.

Linking python#13681
hauntsaninja added a commit that referenced this issue Feb 1, 2023
For the most part, this shortens the Getting Started page, which was
getting a little too long to read comfortably and had caveats that
aren't super important.

The cheat sheet does a really great job of "show, don't tell", so
recommend that even more aggressively for beginners. The BankAccount
example was nice, and the cheat sheet was missing a discussion on
inheritance, so move a version of that over there.

Finally, most users of mypy don't need to know the details of typeshed
and stub files, especially not when getting started. So reframe as a
more generic section about types for third party libraries.

Linking #13681
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Feb 1, 2023
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Feb 2, 2023
JelleZijlstra pushed a commit that referenced this issue Feb 2, 2023
hauntsaninja added a commit that referenced this issue Feb 2, 2023
This just moves content around (with minimal editing to make the moves
make sense).

TypedDict has been the target for several features, including some that
are not yet documented. There was another PEP drafted today that was
TypedDict themed. It's also pretty popular with users.

Linking #13681
hauntsaninja added a commit that referenced this issue Feb 2, 2023
hauntsaninja added a commit that referenced this issue Feb 2, 2023
hauntsaninja added a commit that referenced this issue Feb 2, 2023
hauntsaninja added a commit that referenced this issue Feb 3, 2023
For the most part, this shortens the Getting Started page, which was
getting a little too long to read comfortably and had caveats that
aren't super important.

The cheat sheet does a really great job of "show, don't tell", so
recommend that even more aggressively for beginners. The BankAccount
example was nice, and the cheat sheet was missing a discussion on
inheritance, so move a version of that over there.

Finally, most users of mypy don't need to know the details of typeshed
and stub files, especially not when getting started. So reframe as a
more generic section about types for third party libraries.

Linking #13681
hauntsaninja added a commit that referenced this issue Feb 3, 2023
hauntsaninja added a commit that referenced this issue Feb 3, 2023
This just moves content around (with minimal editing to make the moves
make sense).

TypedDict has been the target for several features, including some that
are not yet documented. There was another PEP drafted today that was
TypedDict themed. It's also pretty popular with users.

Linking #13681
hauntsaninja added a commit that referenced this issue Feb 3, 2023
hauntsaninja added a commit that referenced this issue Feb 3, 2023
hauntsaninja added a commit that referenced this issue Feb 3, 2023
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Mar 29, 2023
Everyone can use future annotations now. Also forward references are
the most type hinting popular question on Stack Overflow, so give a
little more detail.

The IO example should go with standard duck types.

I moved the async example to the bottom. It basically just works as
you'd expect, maybe we should remove it altogether.

Linking python#13681
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Mar 29, 2023
Some of the examples here neither ran nor type checked.
Remove mention and use of deprecated APIs.

Also go into some detail about async generators. Document python#5385
since it comes up not infrequently.

Linking python#13681
hauntsaninja added a commit that referenced this issue Mar 30, 2023
Some of the examples here neither ran nor type checked. Remove mention
and use of deprecated APIs.

Also go into some detail about async generators. Document #5385 since it
comes up not infrequently.

Linking #13681
hauntsaninja added a commit that referenced this issue Mar 30, 2023
Everyone can use future annotations now. Also forward references are the
most type hinting popular question on Stack Overflow, so give a little
more detail.

The IO example should go with standard duck types.

I moved the async example to the bottom. It basically just works as
you'd expect, maybe we should remove it altogether.

Linking #13681

---------

Co-authored-by: Ethan Smith <[email protected]>
hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Jun 18, 2023
@hauntsaninja
Copy link
Collaborator Author

It's been a year since I opened this, closing. I'll still make docs improvements, but 1.0 has been out for a while, so there isn't a specific target any more.

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

No branches or pull requests

2 participants