🧪📝 Integrate sphinx_autodoc_typehints

This allows dropping types from param lists in favor of annotations.

.darglint

@@ -5,5 +5,5 @@
 # * https://github.com/terrencepreilly/darglint/issues/186
 # * https://github.com/wemake-services/wemake-python-styleguide/issues/2287
 docstring_style = sphinx
-enable = DAR104
+# enable = DAR104  # covered by `sphinx_autodoc_typehints`
 strictness = full

bin/pip_constraint_helpers.py

@@ -46,11 +46,8 @@ def get_constraint_file_path(  # noqa: WPS210 -- no way to drop vars
     """Identify the constraints filename for the current environment.
 
     :param req_dir: Requirements directory.
-    :type req_dir: pathlib.Path | str
     :param toxenv: tox testenv.
-    :type toxenv: str
     :param python_tag: Python tag.
-    :type python_tag: str
     :returns: Constraints filename for the current environment.
     """
     sys_platform = sys.platform
@@ -77,9 +74,7 @@ def make_pip_cmd(
     """Inject a lockfile constraint into the pip command if present.
 
     :param pip_args: pip arguments.
-    :type pip_args: list[str]
     :param constraint_file_path: Path to a ``constraints.txt``-compatible file.
-    :type constraint_file_path: pathlib.Path
 
     :returns: pip command.
     """
@@ -98,7 +93,6 @@ def run_cmd(cmd: list[str] | tuple[str, ...]) -> None:
     """Invoke a shell command after logging it.
 
     :param cmd: The command to invoke.
-    :type cmd: list[str] | tuple[str, ...]
     """
     escaped_cmd = shlex.join(cmd)
     print(f'Invoking the following command: {escaped_cmd !s}')  # noqa: WPS421

bin/pip_wrapper.py

@@ -16,11 +16,8 @@ def main(req_dir: str, toxenv: str, *pip_args: tuple[str, ...]) -> None:
     """Invoke pip with the matching constraints file, if present.
 
     :param req_dir: Requirements directory path.
-    :type req_dir: str
     :param toxenv: Tox env name.
-    :type toxenv: str
     :param pip_args: Iterable of args to bypass to pip.
-    :type pip_args: tuple[str, ...]
     """
     constraint_file_path = get_constraint_file_path(
         req_dir=req_dir,

bin/print_lockfile_base_name.py

@@ -15,7 +15,6 @@ def compute_constraint_base_name(toxenv: str) -> str:
     """Get the lock file name stem.
 
     :param toxenv: Name of the tox env.
-    :type toxenv: str
     :returns: A platform-specific lock file base name for tox env.
     """
     return get_constraint_file_path(

bin/resolve_platform_lock_file.py

@@ -17,11 +17,9 @@ def generate_lock_for(
     """Generate a patform-specific lock file for given tox env.
 
     :param req_dir: Requirements directory path.
-    :type req_dir: str
     :param toxenv: Tox env name.
-    :type toxenv: str
-    :param pip_compile_extra_args: Iterable of args to bypass to pip-compile.
-    :type pip_compile_extra_args: tuple[str, ...]
+    :param pip_compile_extra_args: Iterable of args to bypass to pip-
+        compile.
     """
     lock_file_name = get_constraint_file_path(
         req_dir, toxenv, get_runtime_python_tag(),

dependencies/direct/build-docs.in

@@ -3,6 +3,7 @@
 furo  # modern Sphinx theme
 myst-parser[linkify]  # Markdown documents support w/ in-text link detector
 Sphinx  # main docs framework
+sphinx-autodoc-typehints  # gets function param types from annotations
 sphinx-issues  # Sphinx roles providing support for linking GitHub
 sphinx-tabs  # Sphinx directives providing support for HTML tabs
 sphinxcontrib-apidoc  # automatic API pages generator

docs/_ext/spelling_stub_ext.py

@@ -71,7 +71,6 @@ def setup(app: Sphinx) -> dict[str, bool | str]:
     """Initialize the extension.
 
     :param app: A Sphinx application object.
-    :type app: Sphinx
     :returns: Extension metadata as a dict.
     """
     if _EnchantTokenizeFilterBase is object:

docs/conf.py

@@ -73,6 +73,7 @@
 
     # Third-party extensions:
     'myst_parser',  # extended markdown; https://pypi.org/project/myst-parser/
+    'sphinx_autodoc_typehints',  # gets function param types from annotations
     'sphinx_issues',  # implements `:issue:`, `:pr:` and other GH-related roles
     'sphinx_tabs.tabs',
     'sphinxcontrib.apidoc',
@@ -120,6 +121,20 @@
 }
 myst_heading_anchors = 3
 
+# -- Options for sphinx.ext.autodoc extension --------------------------------
+
+autodoc_default_options = {
+    'ignore-module-all': True,
+}
+
+# -- Options for sphinx_autodoc_typehints extension --------------------------
+
+always_document_param_types = True
+always_use_bars_union = True
+typehints_defaults = 'comma'
+typehints_use_signature = True
+typehints_use_signature_return = True
+
 # -- Options for sphinxcontrib.apidoc extension ------------------------------
 
 apidoc_excluded_paths = []