Documentation updates #13681

hauntsaninja · 2022-09-19T00:46:15Z

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.

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.

See #13681

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.

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

See #13681

See python#13681. I'd like to make bigger changes to this page, but still thinking them through

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.

See #13681. I'd like to make bigger changes to this page, but still thinking them through

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.

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".

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 <jelle.zijlstra@gmail.com>

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.

- Mention PEP 604 unions - Separate out the 3.8 stuff to keep things readable Linking python#13681

- 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

See python#13681

See python#13681 More clearly point out the speed cost and the alternative of installing stub packages directly

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

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

Linking python#13681

Linking #13681

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

Linking #13681

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

Linking #13681

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

Linking #13681

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

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

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

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 <ethan@ethanhs.me>

Linking python#13681

hauntsaninja · 2023-08-10T09:14:14Z

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.

hauntsaninja added the feature label Sep 19, 2022

This was referenced Sep 19, 2022

Use the same language in the docs intro and README #13677

Merged

Update cheat sheet docs #13679

Merged

Update runtime_troubles docs #13680

Merged

Mention files confval in "specifying code to check" #13682

Merged

hauntsaninja mentioned this issue Sep 19, 2022

Major update to "using mypy with existing codebase" #13683

Merged

JukkaL pushed a commit that referenced this issue Sep 20, 2022

Update cheat sheet docs (#13679)

e4edea3

See #13681

hauntsaninja added a commit that referenced this issue Sep 20, 2022

Mention files confval in "specifying code to check" (#13682)

e40d214

See #13681

AlexWaygood added the documentation label Sep 21, 2022

hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Sep 26, 2022

Update getting started docs

a9853d1

See python#13681. I'd like to make bigger changes to this page, but still thinking them through

hauntsaninja mentioned this issue Sep 26, 2022

Update getting started docs #13734

Merged

hauntsaninja mentioned this issue Sep 26, 2022

Update type inference and annotations #13736

Merged

hauntsaninja added a commit that referenced this issue Sep 26, 2022

Update getting started docs (#13734)

5f21936

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

Talk about user defined protocols first

20c3e64

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 mentioned this issue Sep 26, 2022

Talk about user defined protocols first #13737

Merged

hauntsaninja mentioned this issue Sep 26, 2022

Reorder sections in running_mypy #13738

Merged

hauntsaninja mentioned this issue Sep 26, 2022

Release 1.0 planning #13685

Closed

17 tasks

hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Oct 12, 2022

Improve cheat sheet

d0c380d

- Mention PEP 604 unions - Separate out the 3.8 stuff to keep things readable Linking python#13681

hauntsaninja mentioned this issue Oct 12, 2022

Improve cheat sheet #13873

Merged

hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Nov 4, 2022

More docs surrounding install-types

428e0b3

See python#13681

hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Nov 4, 2022

Clarify docs surrounding install-types

31402a2

See python#13681 More clearly point out the speed cost and the alternative of installing stub packages directly

hauntsaninja mentioned this issue Nov 4, 2022

Clarify docs surrounding install-types #14003

Merged

hauntsaninja mentioned this issue Feb 1, 2023

Improve some dynamic typing docs #14576

Merged

hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Feb 1, 2023

Improve protocols documentation

12abe2e

Linking python#13681

hauntsaninja mentioned this issue Feb 1, 2023

Improve protocols documentation #14577

Merged

hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Feb 2, 2023

Improve the Common Issues page

ee87699

Linking python#13681

This was referenced Feb 2, 2023

Improve the Common Issues page #14581

Merged

Make a top-level TypedDict page #14584

Merged

Improve Generics docs page #14587

Merged

JelleZijlstra pushed a commit that referenced this issue Feb 2, 2023

Improve some dynamic typing docs (#14576)

ca2694f

Linking #13681

hauntsaninja added a commit that referenced this issue Feb 2, 2023

Improve the Common Issues page (#14581)

2adc98f

Linking #13681

hauntsaninja added a commit that referenced this issue Feb 2, 2023

Improve protocols documentation (#14577)

7bde0d6

Linking #13681

hauntsaninja added a commit that referenced this issue Feb 2, 2023

Improve Generics docs page (#14587)

e2e0fbe

Linking #13681

hauntsaninja added a commit that referenced this issue Feb 3, 2023

Improve some dynamic typing docs (#14576)

dd2c9a6

Linking #13681

hauntsaninja added a commit that referenced this issue Feb 3, 2023

Improve the Common Issues page (#14581)

2cfc46c

Linking #13681

hauntsaninja added a commit that referenced this issue Feb 3, 2023

Improve protocols documentation (#14577)

cb2ec3d

Linking #13681

hauntsaninja added a commit that referenced this issue Feb 3, 2023

Improve Generics docs page (#14587)

9aa1776

Linking #13681

hauntsaninja mentioned this issue Mar 29, 2023

Improvements to cheat sheet #14972

Merged

hauntsaninja mentioned this issue Mar 29, 2023

Improve async documentation #14973

Merged

hauntsaninja added a commit to hauntsaninja/mypy that referenced this issue Jun 18, 2023

Small improvements to protocol documentation

f3c5704

Linking python#13681

hauntsaninja mentioned this issue Jun 18, 2023

Small improvements to protocol documentation #15460

Merged

hauntsaninja closed this as completed Aug 10, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation updates #13681

Documentation updates #13681

hauntsaninja commented Sep 19, 2022 •

edited

hauntsaninja commented Aug 10, 2023

Documentation updates #13681

Documentation updates #13681

Comments

hauntsaninja commented Sep 19, 2022 • edited

hauntsaninja commented Aug 10, 2023

hauntsaninja commented Sep 19, 2022 •

edited