Improved "getting started" documentation.

docs/getting-started.md

@@ -3,16 +3,25 @@
 A static type checker like Pyright can add incremental value to your source code as more type information is provided.
 
 Here is a typical progression:
-1. Install pyright (either the VS Code extension or command-line tool).
-2. Write a minimal `pyrightconfig.json` that defines `include` entries. Place the config file in your project’s top-level directory and commit it to your repo. Alternatively, you can add a pyright section to a `pyproject.toml` file. For additional details and a sample config file, refer to [this documentation](configuration.md).
-3. Optionally enable the `python.analysis.useLibraryCodeForTypes` config option (or pass `--lib` to the command-line tool). This tells Pyright that it should attempt to infer type information from library code if a type stub is not available.
-4. Run pyright over your source base with the default settings. Fix any errors and warnings that it emits.
-5. Enable the `reportMissingTypeStubs` setting in the config file and add (minimal) type stub files for the imported files. You may wish to create a stubs directory within your code base — a location for all of your custom type stub files. Configure the “stubPath” config entry to refer to this directory.
-6. Look for type stubs for the packages you use. Some package authors opt to ship stubs as a separate companion package named that has “-stubs” appended to the name of the original package.
-7. In cases where type stubs do not yet exist for a package you are using, consider creating a custom type stub that defines the portion of the interface that your source code consumes. Check in your custom type stub files and configure pyright to run as part of your continuous integration (CI) environment to keep the project “type clean”.
-8. Incrementally add type annotations to your code files. The annotations that provide most value are on function input parameters, instance variables, and return parameters (in that order). Note that annotation of variables (instance, class and local) requires Python 3.6 or newer.
-9. Enable stricter type checking options like "reportUnknownParameterType", and "reportUntypedFunctionDecorator".
-10. On a file-by-file basis, enable all type checking options by adding the comment `# pyright: strict` somewhere in the file.
-11. Optionally add entire subdirectories to the `strict` config entry to indicate that all files within those subdirectories should be strictly typed.
+
+### 1. Initial Type Checking
+* Install pyright (either the VS Code extension or command-line tool).
+* Write a minimal `pyrightconfig.json` that defines `include` entries. Place the config file in your project’s top-level directory and commit it to your repo. Alternatively, you can add a pyright section to a `pyproject.toml` file. For additional details and a sample config file, refer to [this documentation](configuration.md).
+* Optionally enable the `python.analysis.useLibraryCodeForTypes` config option (or pass `--lib` to the command-line tool). This tells Pyright that it should attempt to infer type information from library code if a type stub is not available.
+* Run pyright over your source base with the default settings. Fix any errors and warnings that it emits. Optionally disable specific diagnostic rules if they are generating too many errors. They can be re-enabled at a later time.
+
+### 2. Types For Imported Libraries
+* Update dependent libraries to recent versions. Many popular libraries have recently added inlined types, which eliminates the need to install or create type stubs.
+* Enable the `reportMissingTypeStubs` setting in the config file and add (minimal) type stub files for the imported files. You may wish to create a stubs directory within your code base — a location for all of your custom type stub files. Configure the “stubPath” config entry to refer to this directory.
+* Look for type stubs for the packages you use. Some package authors opt to ship stubs as a separate companion package named that has “-stubs” appended to the name of the original package.
+* In cases where type stubs do not yet exist for a package you are using, consider creating a custom type stub that defines the portion of the interface that your source code consumes. Check in your custom type stub files and configure pyright to run as part of your continuous integration (CI) environment to keep the project “type clean”.
+
+### 3. Incremental Typing
+* Incrementally add type annotations to your code files. The annotations that provide most value are on function input parameters, instance variables, and return parameters (in that order).
+* Enable stricter type checking options like "reportUnknownParameterType", and "reportUntypedFunctionDecorator".
+
+### 4. Strict Typing
+* On a file-by-file basis, enable all type checking options by adding the comment `# pyright: strict` somewhere in the file.
+* Optionally add entire subdirectories to the `strict` config entry to indicate that all files within those subdirectories should be strictly typed.
 
 

docs/type-concepts.md

@@ -1,6 +1,6 @@
-## Understanding Typing
+## Understanding Static Typing
 
-Getting started with typing in Python is easy, but it’s important to understand a few simple concepts.
+Getting started with static type checking in Python is easy, but it’s important to understand a few simple concepts.
 
 ### Type Declarations
 When you add a type annotation to a variable or a parameter in Python, you are _declaring_ that the symbol will be assigned values that are compatible with that type. You can think of type annotations as a powerful way to comment your code. Unlike text-based comments, these comments are readable by both humans and enforceable by type checkers.
@@ -8,24 +8,16 @@ When you add a type annotation to a variable or a parameter in Python, you are _
 If a variable or parameter has no type annotation, the type checker must assume that any value can be assigned to it. This eliminates the ability for a type checker to identify type incompatibilities.
 
 
-### Debugging Inferred Types
+### Debugging Types
 
-When you want to know the type that the type checker has inferred for an expression, you can use the special `reveal_type()` function:
+When you want to know the type that the type checker has evaluated for an expression, you can use the special `reveal_type()` function:
 
 ```python
 x = 1
 reveal_type(x)  # Type of "x" is "Literal[1]"
 ```
 
-This function is always available and does not need to be imported. When you use Pyright within an IDE, you can also simply hover over an expression to see the inferred type.
-
-You can also see the inferred types of all local variables at once with the `reveal_locals()` function:
-
-```python
-def f(x: int, y: str) -> None:
-    z = 1.0
-    reveal_locals()  # Type of "x" is "int". Type of "y" is "str". Type of "z" is "float".
-```
+This function is always available and does not need to be imported. When you use Pyright within an IDE, you can also simply hover over an identifier to see its evaluated type.
 
 
 ### Type Assignability