From 423104fa7aae882ac329f216371fcf33f39aa47b Mon Sep 17 00:00:00 2001
From: Mike VanDenburgh <michael.vandenburgh@kitware.com>
Date: Tue, 30 Aug 2022 22:02:21 -0400
Subject: [PATCH] Add section to docs for mypy plugin

---
 docs/index.rst |  3 ++-
 docs/mypy.rst  | 29 +++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)
 create mode 100644 docs/mypy.rst

diff --git a/docs/index.rst b/docs/index.rst
index 702654e..e991e4c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -69,6 +69,7 @@ Further documentation
    patterns
    values
    cookbook
+   mypy
    changes
 
 Alternatives
@@ -95,4 +96,4 @@ requests and bug reports:
 
     https://github.com/jazzband/django-configurations/issues
 
-Thanks!
\ No newline at end of file
+Thanks!
diff --git a/docs/mypy.rst b/docs/mypy.rst
new file mode 100644
index 0000000..7b50750
--- /dev/null
+++ b/docs/mypy.rst
@@ -0,0 +1,29 @@
+mypy plugin
+===========
+
+Due to Django's dynamic nature, some `mypy plugins`_ such as `django-stubs`_
+and `djangorestframework-stubs`_ need to (partially) execute your Django code to
+properly derive type information. The django-configurations mypy plugin calls
+``configurations.importer.install()`` to initialize your settings on startup so
+that plugins like django-stubs and djangorestframework-stubs can work with
+projects using django-configurations.
+
+.. _`mypy plugins`: https://mypy.readthedocs.io/en/stable/extending_mypy.html#extending-mypy-using-plugins
+.. _`django-stubs`: https://github.com/typeddjango/django-stubs
+.. _`djangorestframework-stubs`: https://github.com/typeddjango/djangorestframework-stubs
+
+Note, the django-configurations mypy plugin must come before plugins that
+need it in your mypy configuration file. Example ``plugins`` value if configuring
+mypy with ``pyproject.toml``:
+
+
+.. code-block:: toml
+   :emphasize-lines: 9, 11-12
+
+    plugins = [
+        "configurations.mypy_plugin",
+        "mypy_django_plugin.main",
+        "mypy_drf_plugin.main",
+    ]
+
+..