In documentation, use type hints if hand-written param types are not …

…available. #287, #325

CHANGES.rst

@@ -11,6 +11,10 @@ Version 3.10
 
 Unreleased
 
+* In the API documentation,
+  fall back to type hints if hand-written parameter types are not available.
+  Add relevant :ref:`documentation` guidelines to the dev documentation.
+  (:issue:`287`)
 * Add the :mod:`~reader._plugins.share` experimental plugin
   to add social sharing links in the web app.
 

CONTRIBUTING.rst

@@ -61,7 +61,8 @@ Include the following in your patch:
   if you install `pre-commit`_ using the instructions below.
 * Include tests if your patch adds or changes code.
   Make sure the test fails without your patch.
-* Update any relevant documentation pages and docstrings.
+* Update any relevant documentation pages and docstrings;
+  also see :ref:`documentation`.
   Documentation pages and docstrings should be wrapped at 72 characters.
 * Add an entry in ``CHANGES.rst``.
   Use the same style as other entries.

docs/api.rst

@@ -168,6 +168,8 @@ The class hierarchy for :mod:`reader` exceptions is:
 
 
 
+.. _type aliases:
+
 Type aliases
 ------------
 

docs/conf.py

@@ -68,7 +68,14 @@
 todo_include_todos = False
 
 autodoc_member_order = 'bysource'
-autodoc_typehints = 'none'
+# see dev.rst # Documentation
+autodoc_typehints = 'description'
+autodoc_typehints_description_target = 'documented'
+autodoc_type_aliases = {
+    'ResourceInput': 'reader.types.ResourceInput',
+    'AnyResourceInput': 'reader.types.AnyResourceInput',
+    'JSONType': 'reader.types.JSONType',
+}
 
 
 pyproject_toml = read_configuration('../pyproject.toml')

docs/dev.rst

@@ -229,6 +229,50 @@ Making a release (from ``x`` to ``y`` == ``x + 1``):
 * (release.py prompts) trigger Read the Docs build for `<major>.x` (doesn't happen automatically)
 
 
+
+.. _documentation:
+
+Documentation
+-------------
+
+Following are notes about what documentation should look like,
+especially for the stable high-level :doc:`API <api>`,
+since that's what most users will see.
+
+
+We prefer type information in the method description,
+not in the signature,
+since the result is more readable.
+For the same reason,
+we prefer hand-written `Sphinx-style field list types`_.
+
+We still use `autodoc-provided type hints`_
+as fallback for parameters that don't have hand-written types,
+for type documentation for dataclasses,
+and for the unstable :doc:`internal`,
+where it's too much effort to maintain hand-written types.
+
+
+Known issues (October 2023, Sphinx version ~7):
+
+* Overloads are shown with full annotation regardless of autodoc_typehints
+  (known, documented behavior).
+  May get better with https://github.com/sphinx-doc/sphinx/issues/10359.
+
+* Type aliases that do not come from hand-written types
+  but from the autodoc typehints are expanded in-place;
+  this also affects the overload type annotations.
+  The documented work-around is to add the aliases to autodoc_type_aliases.
+
+* Type alias names that appear in parameter types
+  do not link to the documentation in :ref:`type aliases`.
+  May get better with https://github.com/sphinx-doc/sphinx/issues/9705
+
+.. _Sphinx-style field list types: https://www.sphinx-doc.org/en/master/usage/domains/python.html#info-field-lists
+.. _autodoc-provided type hints: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints
+
+
+
 .. _design notes:
 
 Design notes