python · JelleZijlstra · Dec 21, 2021 · Nov 2, 2021 · Nov 3, 2021 · hauntsaninja
diff --git 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 <https://typing.readthedocs.io/>`_.
 
 Building the docs
 =================

diff --git a/docs/index.rst b/docs/index.rst
@@ -6,9 +6,12 @@ Static Typing with Python
    :maxdepth: 2
    :caption: Contents:
 
-   typing Module Documentation <https://docs.python.org/3/library/typing.html>
-   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
@@ -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
@@ -0,0 +1,3 @@
+**********
+The Basics
+**********
diff --git a/docs/source/dependencies.rst 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
@@ -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
@@ -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
@@ -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
@@ -1,3 +1,5 @@
+.. _libraries:
+
 ***********************
 Typing Python Libraries
 ***********************

diff --git a/docs/source/reference.rst 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
@@ -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
@@ -0,0 +1,58 @@
+***************
+The Type System
+***************
+
+Built-in Types
+==============
+
+`typing Module Documentation <https://docs.python.org/3/library/typing.html>`__
+
+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
+^^^^^^^^^^^^