Add numpydoc lint config and fix warnings

To run numpydoc lint, currently a fork of numpydoc is required, due to
an unhandled exception when using sphinx cross-links in the `See Also`
section.  See: numpy/numpydoc#558

As still experimental, numpydoc linting/validation is not checked or
required for future contributions.

Author: j9ac9k

doc/source/conf.py

@@ -35,14 +35,14 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
-    "sphinx.ext.napoleon",
+    "sphinx.ext.napoleon",  # has to be loaded before sphinx_autodoc_typehints
+    "sphinx_autodoc_typehints",
     "sphinx.ext.intersphinx",
     "sphinx_qt_documentation",
     "sphinx_design",
     "sphinx_favicon",
     "sphinxext.rediraffe",
     "sphinxcontrib.images",
-    "sphinx_autodoc_typehints"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -67,6 +67,10 @@
 napoleon_use_admonition_for_notes = True
 napoleon_use_admonition_for_references = True
 napoleon_use_rtype = True
+napoleon_use_param = False
+napoleon_use_keyword = False
+napoleon_attr_annotations = True
+napoleon_use_ivar = True
 napoleon_custom_sections = [("Signals", "params_style")]
 napoleon_preprocess_types = True
 napoleon_type_aliases = {
@@ -77,6 +81,12 @@
     # 'ColorMapSpecifier': ':class:`str`, (:class:`str`, :class:`str`), or :class:`~pyqtgraph.ColorMap`',
 }
 
+
+# makes things far more legible
+python_use_unqualified_type_names = True
+python_display_short_literal_types = True
+
+
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
@@ -135,13 +145,23 @@
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
-autodoc_inherit_docstrings = False
+# Automatically extract typehints when specified and place them in
+# descriptions of the relevant function/method.
+autodoc_typehints = "description"
+autodoc_typehints_format = 'short'
+autodoc_typehints_description_target = 'documented_params'
+autodoc_typehints_defaults = 'braces'
+autodoc_typehints_use_rtype = True
+
+
 autodoc_mock_imports = [
     "scipy",
     "h5py",
     "matplotlib",
 ]
 
+# autodoc_type_aliases = {}
+
 
 # -- Options for HTML output ---------------------------------------------------
 

pyproject.toml

@@ -50,3 +50,19 @@ ignore_errors = true
 [[tool.mypy.overrides]]
 module = "pyqtgraph.flowchart.*" # the list will increase
 ignore_errors = true # will be changed to `false` when it's ready
+
+[tool.numpydoc_validation]
+checks = [
+    "all",   # report on all checks, except the below
+    "EX01",
+    "SA01",
+    "GL08",  # object does not have a docstring
+    "ES01",  # no extended summary found
+]
+# remember to use single quotes for regex in TOML
+exclude = [  # don't report on objects that match any of these regex
+]
+
+override_GL06 = [
+  'Signals' # allow sections to start with "Signals"
+]