update module docs and sphinx config

doc/conf.py

@@ -3,6 +3,31 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+
+# -- Styling: type hints ------------------------------------------------------
+# There are several possible style combinations for rendering types, none of
+# which are optimal in my view. The main switches are:
+# 
+# - Parameter type hints in the signature vs in the separate parameter list
+# - Show type hints as plaintext vs rendered HTML elements
+#
+# The `sphinx_autodoc_typehints` extension enables more context-aware
+# rendering, but it's often way too explicit (e.g., unwrapping type variables)
+# and makes things difficult to read. It does, however, allow for automatic
+# inclusion of default values, which is nice.
+#
+# I'd like type hints to be rendered in an inline code element, but that
+# doesn't happen by default in either case unless you render them in the
+# signature. This is sloppy, however, often just a jumbled mess or parameter
+# names and types. The current preferred option is to just use the native
+# `autodoc` settings for rendering type hints, leaving them out of the
+# signature (for easy heading readability). Type hints in the parameter list
+# are also as short as possible, not rendered crazily (by default this is in
+# italics; not my favorite but it's what we have). No
+# `sphinx_autodoc_typehints` needed at this point; you can toggle it if you
+# want automatic default values or different formatting for type hints.
+
+
 # -- Project information ------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -10,22 +35,32 @@ project = "trainlib"
 copyright = "2026, Sam Griesemer"
 author = "Sam Griesemer"
 
+
 # -- General configuration ----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     "sphinx.ext.autodoc",
+
     # enables a directive to be specified manually that gathers module/object
     # summary details in a table
     "sphinx.ext.autosummary",
+
     # allow viewing source in the HTML pages
     "sphinx.ext.viewcode",
+
     # only really applies to manual docs; docstrings still need RST-like
     "myst_parser",
+
     # enables Google-style docstring formats
     "sphinx.ext.napoleon",
-    # external extension that allows arg types to be inferred by type hints
-    "sphinx_autodoc_typehints",
+
+    # external extension that allows arg types to be inferred by type hints;
+    # without this, type hints show up inside method signatures as plaintext,
+    # but when enabled they are pulled into the parameter/description block and
+    # rendered as native nested markup. What's best for a given package may
+    # vary.
+    # "sphinx_autodoc_typehints",
 ]
 autosummary_generate = True
 autosummary_imported_members = True
@@ -39,10 +74,37 @@ templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
+# -- Options for autodoc ------------------------------------------------------
+# class signatures show up only in __init__ rather than at the class header;
+# generally cleaner, avoids redundancy
+autodoc_class_signature = "separated"
+
+# if `sphinx_autodoc_typehints` extension is enabled, this is redundant: type
+# hints are rendered natively and already show up in the parameter block. If
+# it's disabled, this setting will do the same job of moving the types to the
+# parameter block, but it renders them in plaintext (with links to in-package
+# type refs).
+autodoc_typehints = "description"  # "signature"
+autodoc_typehints_format = "short"
+autodoc_preserve_defaults = True
+autodoc_use_type_comments = False
+python_use_unqualified_type_names = True
+
+# push parameters to their own lines in the signature block
+# python_maximum_signature_line_length = 60
+
+
+# -- Options for autodoc_typehints --------------------------------------------
+# always_use_bars_union = True  # always on for Python 3.14+
+# typehints_defaults = "braces-after"  # render defaults in param block
+# typehints_use_signature = False  # False is default; enable if wanted in sig
+# always_document_param_types = True  # show types even when not in docstring
+
+
 # -- Options for HTML output --------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "furo"
+html_theme = "furo"  # "pydata_sphinx_theme"
 html_static_path = ["_static"]
 
 # html_sidebars = {