Display autodoc type information more legibly

[simonw]

https://sqlite-utils.datasette.io/en/3.25/reference.html#sqlite_utils.db.Table.insert looks like this at the moment:

[simonw]

Hint from https://twitter.com/AdamChainz/status/1502311047612575745

Try:

autodoc_typehints = 'description'

For a list-of-arguments format

https://sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints

[simonw]

Definitely an improvement!

It does highlight that I'm not currently using the :param XXX: description syntax though, which should move my descriptions of each parameter into that generated list.

[simonw]

Applying this change fixes that:

diff --git a/sqlite_utils/db.py b/sqlite_utils/db.py
index 3bc528f..2a79711 100644
--- a/sqlite_utils/db.py
+++ b/sqlite_utils/db.py
@@ -2293,18 +2293,18 @@ class Table(Queryable):
         """
         Apply conversion function ``fn`` to every value in the specified columns.
 
-        - ``columns`` - a single column or list of string column names to convert.
-        - ``fn`` - a callable that takes a single argument, ``value``, and returns it converted.
-        - ``output`` - optional string column name to write the results to (defaults to the input column).
-        - ``output_type`` - if the output column needs to be created, this is the type that will be used
+        :param columns: a single column or list of string column names to convert.
+        :param fn: a callable that takes a single argument, ``value``, and returns it converted.
+        :param output: optional string column name to write the results to (defaults to the input column).
+        :param output_type: if the output column needs to be created, this is the type that will be used
           for the new column.
-        - ``drop`` - boolean, should the original column be dropped once the conversion is complete?
-        - ``multi`` - boolean, if ``True`` the return value of ``fn(value)`` will be expected to be a
+        :param drop: boolean, should the original column be dropped once the conversion is complete?
+        :param multi: boolean, if ``True`` the return value of ``fn(value)`` will be expected to be a
           dictionary, and new columns will be created for each key of that dictionary.
-        - ``where`` - a SQL fragment to use as a ``WHERE`` clause to limit the rows to which the conversion
+        :param where: a SQL fragment to use as a ``WHERE`` clause to limit the rows to which the conversion
           is applied, for example ``age > ?`` or ``age > :age``.
-        - ``where_args`` - a list of arguments (if using ``?``) or a dictionary (if using ``:age``).
-        - ``show_progress`` - boolean, should a progress bar be displayed?
+        :param where_args: a list of arguments (if using ``?``) or a dictionary (if using ``:age``).
+        :param show_progress: boolean, should a progress bar be displayed?
 
         See :ref:`python_api_convert`.
         """

[simonw]

Well this is a huge improvement!

https://sqlite-utils.datasette.io/en/latest/reference.html#sqlite_utils.db.Table.insert

I'm not crazy about the extracts=<sqlite_utils.db.Default object> thing though - I wonder if there's a neat way to customize that to be less verbose?

[simonw]

I'm really happy with this improvement.