finicky autodoc nuances, fixed type aliases in signatures

Author: skysomorphic

docs/conf.py

@@ -36,17 +36,12 @@
 
 autodoc_member_order = "bysource"
 autodoc_type_aliases = {
-    "Async": "qbreader.asynchronous.Async",
-    "Sync": "qbreader.synchronous.Sync",
-    "Tossup": "qbreader.types.Tossup",
-    "Bonus": "qbreader.types.Bonus",
-    "Category": "qbreader.types.Category",
-    "Subcategory": "qbreader.types.Subcategory",
-    "Difficulty": "qbreader.types.Difficulty",
-    "QueryResponse": "qbreader.types.QueryResponse",
-    "Directive": "qbreader.types.Directive",
-    "AnswerJudgement": "qbreader.types.AnswerJudgement",
-    "Packet": "qbreader.types.Packet",
+    "QuestionType": "qbreader.types.QuestionType",
+    "SearchType": "qbreader.types.SearchType",
+    "ValidDifficulties": "qbreader.types.ValidDifficulties",
+    "UnnormalizedDifficulty": "qbreader.types.UnnormalizedDifficulty",
+    "UnnormalizedCategory": "qbreader.types.UnnormalizedCategory",
+    "UnnormalizedSubcategory": "qbreader.types.UnnormalizedSubcategory",
 }
 
 # -- Options for HTML output -------------------------------------------------
@@ -58,5 +53,6 @@
 html_static_path = ["_static"]
 
 intersphinx_mapping = {
-    "py": ("https://docs.python.org/3", None),
+    "python": ("https://docs.python.org/3", None),
+    "aiohttp": ("https://docs.aiohttp.org/en/stable/", None),
 }

qbreader/__init__.py

@@ -1,34 +1,30 @@
-"""The official qbreader API python wrapper."""
+"""The official qbreader API python wrapper.
+
+    .. note::
+        Even though useful type aliases defined in `qbreader.types` are reexported here,
+        they are not documented here by `sphinx-autodoc`, but are documented in the
+        `types` module.
+
+        See also:
+            * https://github.com/sphinx-doc/sphinx/issues/8547
+            * https://github.com/sphinx-doc/sphinx/issues/1063
+"""
 
 import importlib.metadata
 
+import qbreader.types as types
 from qbreader.asynchronous import Async
 from qbreader.synchronous import Sync
-from qbreader.types import (
-    AnswerJudgement,
-    Bonus,
-    Category,
-    Difficulty,
-    Directive,
-    Packet,
-    QueryResponse,
-    Subcategory,
-    Tossup,
-)
+from qbreader.types import *
 
 __version__ = importlib.metadata.version("qbreader")
 __all__ = (
     "Async",
     "Sync",
-    "Tossup",
-    "Bonus",
-    "Category",
-    "Subcategory",
-    "Difficulty",
-    "QueryResponse",
-    "Directive",
-    "AnswerJudgement",
-    "Packet",
+    "types",
 )
 
+# add all symbols from qbreader.types to __all__
+__all__ += types.__all__
+
 del importlib

qbreader/_api_utils.py

@@ -1,5 +1,7 @@
 """Useful functions used by both the asynchronous and synchronous API wrappers."""
 
+from __future__ import annotations
+
 import warnings
 from enum import Enum, EnumType
 from typing import Iterable, Optional, Union

qbreader/asynchronous.py

@@ -1,5 +1,7 @@
 """Directly access the qbreader API asynchronously."""
 
+from __future__ import annotations
+
 from typing import Optional, Self, Type
 
 import aiohttp

qbreader/synchronous.py

@@ -1,5 +1,7 @@
 """Directly access the qbreader API synchronously."""
 
+from __future__ import annotations
+
 from typing import Optional, Self
 
 import requests

qbreader/types.py

@@ -492,7 +492,10 @@ def __str__(self) -> str:
 QuestionType: TypeAlias = Union[
     Literal["tossup", "bonus", "all"], Type[Tossup], Type[Bonus]
 ]
+"""Type alias for question types."""
+
 SearchType: TypeAlias = Literal["question", "answer", "all"]
+"""Type alias for query search types."""
 
 ValidDifficulties: TypeAlias = Literal[
     0,
@@ -518,12 +521,41 @@ def __str__(self) -> str:
     "9",
     "10",
 ]
+"""Type alias for valid difficulties."""
+
 UnnormalizedDifficulty: TypeAlias = Optional[
     Union[Difficulty, ValidDifficulties, Iterable[Union[Difficulty, ValidDifficulties]]]
 ]
+"""Type alias for unnormalized difficulties. Union of `Difficulty`, `ValidDifficulties`,
+and `collections.abc.Iterable` containing either."""
+
 UnnormalizedCategory: TypeAlias = Optional[
     Union[Category, str, Iterable[Union[Category, str]]]
 ]
+"""Type alias for unnormalized categories. Union of `Category`, `str`, and
+`collections.abc.Iterable` containing either."""
+
 UnnormalizedSubcategory: TypeAlias = Optional[
     Union[Subcategory, str, Iterable[Union[Subcategory, str]]]
 ]
+"""Type alias for unnormalized subcategories. Union of `Subcategory`, `str`, and
+`collections.abc.Iterable` containing either."""
+
+
+__all__ = (
+    "Tossup",
+    "Bonus",
+    "Packet",
+    "QueryResponse",
+    "AnswerJudgement",
+    "Category",
+    "Subcategory",
+    "Difficulty",
+    "Directive",
+    "QuestionType",
+    "SearchType",
+    "ValidDifficulties",
+    "UnnormalizedDifficulty",
+    "UnnormalizedCategory",
+    "UnnormalizedSubcategory",
+)