From 22961324e1a1b38972ef4c32eee821b60ceda760 Mon Sep 17 00:00:00 2001
From: Russell Martin <russell@rjm.li>
Date: Wed, 12 Jun 2024 21:39:16 -0400
Subject: [PATCH] Custom type hint doc formatting for `TypeAlias`, `TypeVar`

---
 core/pyproject.toml    |  1 +
 core/src/toga/types.py |  3 +++
 docs/conf.py           | 26 ++++++++++++++++++++++++++
 3 files changed, 30 insertions(+)

diff --git a/core/pyproject.toml b/core/pyproject.toml
index 0624fc8465..15929b9499 100644
--- a/core/pyproject.toml
+++ b/core/pyproject.toml
@@ -91,6 +91,7 @@ docs = [
     # Sphinx 2024.2.4 deprecated support for Python 3.8
     "sphinx-autobuild == 2021.3.14 ; python_version < '3.9'",
     "sphinx-autobuild == 2024.4.16 ; python_version >= '3.9'",
+    "sphinx-autodoc-typehints == 2.1.1",
     "sphinx-csv-filter == 0.4.1",
     "sphinx-copybutton == 0.5.2",
     "sphinx-toolbox == 3.5.0",
diff --git a/core/src/toga/types.py b/core/src/toga/types.py
index b50553cb1f..1f349adb12 100644
--- a/core/src/toga/types.py
+++ b/core/src/toga/types.py
@@ -13,6 +13,9 @@
 
     PositionT: TypeAlias = toga.Position | tuple[int, int]
     SizeT: TypeAlias = toga.Size | tuple[int, int]
+else:
+    PositionT = None
+    SizeT = None
 
 
 class LatLng(NamedTuple):
diff --git a/docs/conf.py b/docs/conf.py
index 8ceba40f04..1675b60010 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -32,6 +32,7 @@
     "sphinx_tabs.tabs",
     "crate.sphinx.csv",
     "sphinx_copybutton",
+    "sphinx_autodoc_typehints",
     "sphinx_toolbox.more_autodoc.autonamedtuple",
     "sphinx_toolbox.more_autodoc.autoprotocol",
     "sphinx.ext.intersphinx",
@@ -73,6 +74,8 @@
 }
 autodoc_typehints = "description"
 
+autodoc_type_aliases = {"IconContentT": "toga.icons.IconContentT"}
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 # language = None
@@ -372,3 +375,26 @@ def autodoc_process_signature(
 
 # If this is True, todolist produce output without file path and line, The default is False.
 # todo_link_only = False
+
+
+# Disable WARNING: cannot cache unpickable configuration value: 'typehints_formatter'
+suppress_warnings = ["config.cache"]
+
+always_use_bars_union = True
+
+from pathlib import Path  # noqa: E402
+from typing import Union  # noqa: E402
+
+import toga  # noqa: E402
+
+
+def my_typehints_formatter(annotation, config):
+    # print(f"({type(annotation)}) {str(annotation)=}")
+    if annotation == Union[str, Path, toga.Icon, None]:
+        return "``IconContentT``"
+    elif annotation == toga.widgets.base.StyleT:
+        return "``StyleT``"
+    return None
+
+
+typehints_formatter = my_typehints_formatter