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,9 @@
 
  PositionT: TypeAlias = toga.Position | tuple[int, int]
  SizeT: TypeAlias = toga.Size | tuple[int, int]
+else:
+ 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",
@@ -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