Custom type hint doc formatting for TypeAlias, TypeVar

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",

core/src/toga/types.py

@@ -13,6 +13,10 @@
 
     PositionT: TypeAlias = toga.Position | tuple[int, int]
     SizeT: TypeAlias = toga.Size | tuple[int, int]
+else:
+    # sphinx-autodoc-typehints errors when these are gated with TYPE_CHECKING...
+    PositionT = None
+    SizeT = None
 
 
 class LatLng(NamedTuple):

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",
@@ -372,3 +373,23 @@ 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 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