🧪📝 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',
@@ -126,6 +127,14 @@
     '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 = []

src/awx_plugins/interfaces/_temporary_private_container_api.py

@@ -28,17 +28,13 @@ def get_incontainer_path(
     to ``/runner``.
 
     :param path: Host-side path view.
-    :type path: os.PathLike[str] | str
-
     :param private_data_dir: Host-side directory mounted to ``/runner``
                              in container.
-    :type private_data_dir: os.PathLike[str] | str
 
     :raises RuntimeError: If the private data directory is not absolute or does
                           not contain the path.
 
     :returns: In-container path.
-    :rtype: str
     """
     if not os.path.isabs(private_data_dir):
         raise RuntimeError('The private_data_dir path must be absolute')

src/awx_plugins/interfaces/_temporary_private_django_api.py

@@ -14,15 +14,13 @@ def get_vmware_certificate_validation_setting() -> bool:
         This is a stub for when there is no Django in the environment.
 
         :returns: Whether the certificates should be validated.
-        :rtype: bool
         """
         return True
 else:  # FIXME: eventually, this should not exist  # pragma: no cover
     def get_vmware_certificate_validation_setting() -> bool:  # noqa: WPS440
         """Retrieve VMware certificate validation platform toggle.
 
         :returns: Whether the certificates should be validated.
-        :rtype: bool
         """
         return settings.VMWARE_VALIDATE_CERTS
 
@@ -38,9 +36,7 @@ def gettext_lazy(message: str) -> str:  # noqa: WPS440
         """Emulate a Django-imported lazy translator.
 
         :param message: Translatable string.
-        :type message: str
         :returns: Whatever's been passed in.
-        :rtype: str
         """
         return message
 
@@ -56,9 +52,7 @@ def gettext_noop(message: str) -> str:  # noqa: WPS440
         """Emulate a Django-imported no-op.
 
         :param message: Translatable string.
-        :type message: str
         :returns: Whatever's been passed in.
-        :rtype: str
         """
         return message
 

src/awx_plugins/interfaces/_temporary_private_licensing_api.py

@@ -15,7 +15,6 @@ def detect_server_product_name() -> str:
     """Compute the official runtime name.
 
     :returns: Runtime name.
-    :rtype: str
     """
     custom_version_file_present = pathlib.Path(
         '/var/lib/awx/.tower_version',