From a6b885c7881055c823e04bdcea197bab748eaee2 Mon Sep 17 00:00:00 2001
From: Hironori Yamamoto <mr.nikoru918@gmail.com>
Date: Sat, 21 Sep 2024 01:27:01 +0900
Subject: [PATCH] docs: add docs for mypy plugin

---
 doc/conf.py   |  2 ++
 doc/index.rst |  1 +
 doc/mypy.rst  | 42 ++++++++++++++++++++++++++++++++++++++++++
 tox.ini       |  3 +--
 4 files changed, 46 insertions(+), 2 deletions(-)
 create mode 100644 doc/mypy.rst

diff --git a/doc/conf.py b/doc/conf.py
index 2cc4dc8ab4..d1ca23dd3c 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -338,6 +338,8 @@ def _warn_node(self, msg, node, *args, **kwargs):
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 
+autodoc_mock_imports = ["mypy"]
+
 # Some regression introduced
 # https://github.com/sphinx-doc/sphinx/issues/2330
 # https://github.com/spotify/luigi/pull/1555
diff --git a/doc/index.rst b/doc/index.rst
index e3d408eb19..2215838b64 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -22,6 +22,7 @@ Table of Contents
    configuration.rst
    logging.rst
    design_and_limitations.rst
+   mypy.rst
 
 API Reference
 -------------
diff --git a/doc/mypy.rst b/doc/mypy.rst
new file mode 100644
index 0000000000..51b38d03eb
--- /dev/null
+++ b/doc/mypy.rst
@@ -0,0 +1,42 @@
+Mypy plugin
+--------------
+
+Mypy plugin provides type checking for ``luigi.Task`` using Mypy.
+
+Require Python 3.8 or later.
+
+How to use
+~~~~~~~~~~
+
+Configure Mypy to use this plugin by adding the following to your ``mypy.ini`` file:
+
+.. code:: ini
+
+    [mypy]
+    plugins = luigi.mypy
+
+or by adding the following to your ``pyproject.toml`` file:
+
+.. code:: toml
+
+    [tool.mypy]
+    plugins = ["luigi.mypy"]
+
+Then, run Mypy as usual.
+
+Examples
+~~~~~~~~
+
+For example the following code linted by Mypy:
+
+.. code:: python
+
+    import luigi
+
+
+    class MyTask(luigi.Task):
+        foo: int = luigi.IntParameter()
+        bar: str = luigi.Parameter()
+
+    MyTask(foo=1, bar='2')   # OK
+    MyTask(foo='1', bar='2')  # Error: Argument 1 to "Foo" has incompatible type "str"; expected "int"
diff --git a/tox.ini b/tox.ini
index 8eb1acd8f9..f9e93d6889 100644
--- a/tox.ini
+++ b/tox.ini
@@ -139,12 +139,11 @@ deps =
     sqlalchemy
     boto3
     jinja2==3.0.3
-    Sphinx>=1.4.4,<1.5
+    Sphinx>=1.4.4,<2.0
     sphinx_rtd_theme
     azure-storage-blob<=12.20.0
     prometheus-client==0.5.0
     alabaster<0.7.13
-    mypy
 commands =
 # build API docs
     sphinx-apidoc -o doc/api -T luigi --separate