Improve documentation for typed dicts (#441)

Author: cthoyt

docs/source/conf.py

@@ -74,6 +74,7 @@
     "sphinx_click.ext",
     "sphinx_automodapi.automodapi",
     "sphinx_automodapi.smart_resolver",
+    "sphinx_toolbox.more_autodoc.autotypeddict",
 ]
 
 # generate autosummary pages
@@ -258,3 +259,7 @@
 
 # Output SVG inheritance diagrams
 graphviz_output_format = "svg"
+
+# sphinx_autodoc_typehints configuration
+always_document_param_types = True
+autodoc_typehints = "description"

docs/source/usage.rst

@@ -1,5 +1,8 @@
-Usage
-=====
+Reference
+=========
 
-.. automodule:: pyobo
-    :members:
+.. automodapi:: pyobo
+    :no-heading:
+
+.. automodapi:: pyobo.constants
+    :no-heading:

pyproject.toml

@@ -102,6 +102,7 @@ docs = [
     "sphinx-rtd-theme>=3.0",
     "sphinx-click", 
     "sphinx_automodapi",
+    "sphinx_toolbox",
 ]
 lint = [
     "ruff",

src/pyobo/constants.py

@@ -14,8 +14,21 @@
 
 __all__ = [
     "DATABASE_DIRECTORY",
+    "DEFAULT_PREFIX_MAP",
+    "ONTOLOGY_GETTERS",
+    "PROVENANCE_PREFIXES",
     "RAW_DIRECTORY",
     "SPECIES_REMAPPING",
+    "DatabaseKwargs",
+    "GetOntologyKwargs",
+    "IterHelperHelperDict",
+    "LookupKwargs",
+    "OntologyFormat",
+    "OntologyPathPack",
+    "SlimGetOntologyKwargs",
+    "check_should_cache",
+    "check_should_force",
+    "check_should_use_tqdm",
 ]
 
 logger = logging.getLogger(__name__)
@@ -96,6 +109,8 @@
 
 NCBITAXON_PREFIX = "ncbitaxon"
 DATE_FORMAT = "%d:%m:%Y %H:%M"
+
+#: Prefixes for resources that are considered as provenance
 PROVENANCE_PREFIXES = {
     "pubmed",
     "pmc",
@@ -117,13 +132,21 @@
 class DatabaseKwargs(TypedDict):
     """Keyword arguments for database CLI functions."""
 
+    #: Should strict identifier parsing be enabled?
     strict: bool
+    #: Should re-download and re-processing be forced?
     force: bool
+    #: Should re-processing be forced?
     force_process: bool
-    skip_pyobo: bool
+
+    #: Should a progress bar be used?
+    use_tqdm: bool
+    #: Skip all prefixes lexicographically sorted below the given prefix
     skip_below: str | None
+    #: If true, skips prefixes that are ontologized as sources in PyOBO
+    skip_pyobo: bool
+    #: An enumerated set of prefixes to skip
     skip_set: set[str] | None
-    use_tqdm: bool
 
 
 class SlimGetOntologyKwargs(TypedDict):
@@ -134,8 +157,11 @@ class SlimGetOntologyKwargs(TypedDict):
     only a single ontology is requested.
     """
 
+    #: Should strict identifier parsing be enabled?
     strict: NotRequired[bool]
+    #: Should re-download and re-processing be forced?
     force: NotRequired[bool]
+    #: Should re-processing be forced?
     force_process: NotRequired[bool]
 
 
@@ -145,8 +171,11 @@ class GetOntologyKwargs(SlimGetOntologyKwargs):
     This dictionary doesn't contain ``prefix`` since this is always explicitly handled.
     """
 
+    #: The version of the ontology to get
     version: NotRequired[str | None]
+    #: Should the cache be used?
     cache: NotRequired[bool]
+    #: Should a progress bar be used?
     use_tqdm: NotRequired[bool]
 
 
@@ -186,12 +215,17 @@ class IterHelperHelperDict(SlimGetOntologyKwargs):
     :func:`pyobo.get_ontology` in each iteration.
     """
 
+    #: Should a progress bar be used?
     use_tqdm: bool
+    #: Skip all prefixes lexicographically sorted below the given prefix
     skip_below: str | None
+    #: If true, skips prefixes that are ontologized as sources in PyOBO
     skip_pyobo: bool
+    #: An enumerated set of prefixes to skip
     skip_set: set[str] | None
 
 
+#: The ontology format
 OntologyFormat: TypeAlias = Literal["obo", "owl", "json", "rdf"]
 
 #: from table 2 of the Functional OWL syntax definition
@@ -207,7 +241,9 @@ class IterHelperHelperDict(SlimGetOntologyKwargs):
 class OntologyPathPack(NamedTuple):
     """A format and path tuple."""
 
+    #: The ontology format
     format: OntologyFormat
+    #: The path to the ontology file
     path: Path
 
 

src/pyobo/getters.py

@@ -45,8 +45,14 @@
 from .version import get_git_hash, get_version
 
 __all__ = [
+    "REQUIRES_NO_ROBOT_CHECK",
+    "SKIP",
     "NoBuildError",
+    "UnhandledFormatError",
+    "db_output_helper",
     "get_ontology",
+    "iter_helper",
+    "iter_helper_helper",
 ]
 
 logger = logging.getLogger(__name__)
@@ -112,8 +118,6 @@ def get_ontology(
 
     :returns: An OBO object
 
-    :raises OnlyOWLError: If the OBO foundry only has an OWL document for this resource.
-
     Alternate usage if you have a custom url
 
     .. code-block:: python
@@ -220,7 +224,8 @@ def _ensure_ontology_path(
     return None
 
 
-SKIP = {
+#: A dictioanry of prefixes to skip during full build with reasons as values
+SKIP: dict[str, str] = {
     "ncbigene": "too big, refs acquired from other dbs",
     "pubchem.compound": "top big, can't deal with this now",
     "gaz": "Gazetteer is irrelevant for biology",