Add a tutorial for using external libraries (#2046)

Author: srittau

docs/guides/writing_stubs.rst

@@ -5,7 +5,8 @@ Writing and Maintaining Stub Files
 **********************************
 
 Stub files are a means of providing type information for Python modules.
-For a full reference, refer to :ref:`stub-files`.
+For a quick introduction, see :ref:`external_libraries`. For a full reference,
+refer to :ref:`distributing-type`.
 
 Maintaining stubs can be a little cumbersome because they are separated from the
 implementation. This page lists some tools that make writing and maintaining

docs/index.rst

@@ -2,6 +2,17 @@
 Static Typing with Python
 *************************
 
+Tutorials
+=========
+
+..
+   Keep in sync with tutorials/index.rst.
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorials/external_libraries
+
 Guides
 ======
 

docs/tutorials/external_libraries.rst

@@ -0,0 +1,42 @@
+.. _external_libraries:
+
+************************
+Using External Libraries
+************************
+
+.. seealso::
+    If you are looking for information on how to write type hints for
+    external libraries, see the :ref:`writing_stubs` guide.
+
+Many external libraries -- whether installed from the
+`Python Package Index <https://pypi.org/>`_ (PyPI) or from other sources --
+provide their own type hints. This is indicated by the presence of a
+``py.typed`` file in the library's root directory. If you install such a
+library, you can use it with any type checker without any additional
+configuration.
+
+Type hints can either be included in the library's source code the same way
+as in your own code, or they can be provided in separate so-called
+*stub files*. Stub files are named ``<module>.pyi`` and contain only type
+hints, without any implementation.
+
+For libraries that don't include their own type hints, a separate
+*stub package* may provide them. These stub packages are often written by the
+library authors themselves, by the contributors to the
+`typeshed <https://github.com/python/typeshed>`_ project, or by third-party
+contributors. These packages are usually named ``types-<library>``
+or ``<library>-stubs``. These packages can be installed from PyPI as usual, and
+they will be automatically discovered by type checkers::
+
+    pip install requests types-requests
+
+.. warning::
+
+    The usual security considerations apply when installing third-party
+    packages. Only install packages from sources you trust. Stub packages
+    have the same security implications as any other package.
+
+..
+   TODO: Once development dependencies are supported by pyproject.toml,
+   and described in https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
+   we should recommend installing type stubs as a development dependency.

docs/tutorials/index.rst

@@ -0,0 +1,15 @@
+:orphan:
+
+*********************
+Type System Tutorials
+*********************
+
+..
+   Keep in sync with docs/index.rst.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   external_libraries