diff --git a/docs/README.rst b/docs/README.rst index 50c7fa4b..6b431c81 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -5,7 +5,7 @@ Reading the docs ================= The live documentation for Python's static typing can be found at -[typing.readthedocs.io](https://typing.readthedocs.io/). +`typing.readthedocs.io `_. Building the docs ================= diff --git a/docs/index.rst b/docs/index.rst index ba838454..f75d4c21 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,9 +6,12 @@ Static Typing with Python :maxdepth: 2 :caption: Contents: - typing Module Documentation - source/libraries - source/stubs + source/introduction + +.. toctree:: + :maxdepth: 3 + + source/reference Indices and tables diff --git a/docs/source/annotations.rst b/docs/source/annotations.rst new file mode 100644 index 00000000..ea5c471f --- /dev/null +++ b/docs/source/annotations.rst @@ -0,0 +1,68 @@ +**************** +Type Annotations +**************** + +Functions +========= + +Parameters +---------- + +Asynchronous Functions +---------------------- + +Generators +---------- + +Lambdas +------- + + +Classes +======= + +Overloads and Overrides +----------------------- + +Instance vs. Class Attributes +----------------------------- + +Final attributes +---------------- + +Abstract base classes +--------------------- + + +Globals +======= + + +Attributes +========== + + +Locals +====== + +Empty Containers +---------------- + + +Runtime Considerations +====================== + +Comment vs. Inline Support +-------------------------- + +Forward References +------------------ + +Generic types that don't implement `__getitem__` +------------------------------------------------ + +Conditioning on static type checking +------------------------------------ + +from `__future__` import annotations +------------------------------------ diff --git a/docs/source/basics.rst b/docs/source/basics.rst new file mode 100644 index 00000000..9b2bf52a --- /dev/null +++ b/docs/source/basics.rst @@ -0,0 +1,3 @@ +********** +The Basics +********** diff --git a/docs/source/dependencies.rst b/docs/source/dependencies.rst new file mode 100644 index 00000000..b16fa639 --- /dev/null +++ b/docs/source/dependencies.rst @@ -0,0 +1,12 @@ +************************** +Libraries and Dependencies +************************** + +:doc:`libraries` + +Typeshed +======== + + +Placeholder Stubs +================= diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 00000000..906e2779 --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,23 @@ +************************** +Frequently Asked Questions +************************** + + +Why Types? +========== + + +Unsupported Python Features +=========================== + + +Common Errors +============= + + +Typing PEPs +=========== + + +Relevant Talks and Resources +============================ diff --git a/docs/source/inference.rst b/docs/source/inference.rst new file mode 100644 index 00000000..291dec48 --- /dev/null +++ b/docs/source/inference.rst @@ -0,0 +1,28 @@ +************** +Type Inference +************** + +Rules for local inference +========================= + +Explicit vs. Implicit Local Types +--------------------------------- + +Changing Types +============== + +Asserts +------- + +Casts +----- + +Type Guards +----------- + + +Protocols and Duck Typing +========================= + +Callback Protocols +------------------ diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst new file mode 100644 index 00000000..fb973559 --- /dev/null +++ b/docs/source/introduction.rst @@ -0,0 +1,41 @@ +******************************* +Introduction to Types in Python +******************************* + + +Background +========== + +How to read type annotations +---------------------------- + +When and why types are useful +----------------------------- + + +Gradual Typing: Static Types in a Dynamic Language +================================================== + +Opt-in type checking +-------------------- + +Type stubs +---------- + +:doc:`stubs` + +Strategies for increasing coverage +---------------------------------- + + +Getting Started +=============== + +Python type checkers +-------------------- + +How to annotate an existing codebase +------------------------------------ + +Typeshed +-------- diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst index 0c1942c3..d0717818 100644 --- a/docs/source/libraries.rst +++ b/docs/source/libraries.rst @@ -1,3 +1,5 @@ +.. _libraries: + *********************** Typing Python Libraries *********************** diff --git a/docs/source/reference.rst b/docs/source/reference.rst new file mode 100644 index 00000000..a5f321ed --- /dev/null +++ b/docs/source/reference.rst @@ -0,0 +1,15 @@ +********************* +Type System Reference +********************* + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + basics + type_system + annotations + inference + type_compatibility + dependencies + faq diff --git a/docs/source/type_compatibility.rst b/docs/source/type_compatibility.rst new file mode 100644 index 00000000..43ebd32b --- /dev/null +++ b/docs/source/type_compatibility.rst @@ -0,0 +1,17 @@ +****************** +Type Compatibility +****************** + + +The Class Hierarchy +=================== + +Mutable Containers +------------------ + +Comparing Callables: Covariance and Contravariance +-------------------------------------------------- + + +Metaclasses +=========== diff --git a/docs/source/type_system.rst b/docs/source/type_system.rst new file mode 100644 index 00000000..6d7954b8 --- /dev/null +++ b/docs/source/type_system.rst @@ -0,0 +1,58 @@ +*************** +The Type System +*************** + +Built-in Types +============== + +`typing Module Documentation `__ + +Built-in Primitives +------------------- + +Built-in operators +------------------ + +Advanced Types +-------------- + + +Simple User-Defined Types +========================= + + +Type Aliases +============ + +Recursive Aliases +----------------- + + +Data Structures +=============== + +Typed Dictionary +---------------- + +Dataclass +--------- + + +Generic Types +============= + + +Type Variables +============== + +TypeVar +------- + +Variadics +--------- + +ParamSpec +^^^^^^^^^ + +TypeVarTuple +^^^^^^^^^^^^