diff --git a/.darglint b/.darglint index 1991e0f7..927493c6 100644 --- a/.darglint +++ b/.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 diff --git a/bin/pip_constraint_helpers.py b/bin/pip_constraint_helpers.py index 47a99b84..86721b5d 100644 --- a/bin/pip_constraint_helpers.py +++ b/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 diff --git a/bin/pip_wrapper.py b/bin/pip_wrapper.py index c5467a3d..2ccedc4b 100644 --- a/bin/pip_wrapper.py +++ b/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, diff --git a/bin/print_lockfile_base_name.py b/bin/print_lockfile_base_name.py index 272b43b0..09e67dae 100755 --- a/bin/print_lockfile_base_name.py +++ b/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( diff --git a/bin/resolve_platform_lock_file.py b/bin/resolve_platform_lock_file.py index 95a0953c..565ca083 100644 --- a/bin/resolve_platform_lock_file.py +++ b/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(), diff --git a/dependencies/direct/build-docs.in b/dependencies/direct/build-docs.in index 89749a13..500dff09 100644 --- a/dependencies/direct/build-docs.in +++ b/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 diff --git a/docs/_ext/spelling_stub_ext.py b/docs/_ext/spelling_stub_ext.py index 2835fdac..e16d1213 100644 --- a/docs/_ext/spelling_stub_ext.py +++ b/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: diff --git a/docs/conf.py b/docs/conf.py index c34c9eb9..239b7a35 100644 --- a/docs/conf.py +++ b/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 = [] diff --git a/src/awx_plugins/interfaces/_temporary_private_container_api.py b/src/awx_plugins/interfaces/_temporary_private_container_api.py index 6c4768b3..31b1d0ed 100644 --- a/src/awx_plugins/interfaces/_temporary_private_container_api.py +++ b/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') diff --git a/src/awx_plugins/interfaces/_temporary_private_django_api.py b/src/awx_plugins/interfaces/_temporary_private_django_api.py index 1a39e4ce..277d8c2b 100644 --- a/src/awx_plugins/interfaces/_temporary_private_django_api.py +++ b/src/awx_plugins/interfaces/_temporary_private_django_api.py @@ -14,7 +14,6 @@ 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 @@ -22,7 +21,6 @@ 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 diff --git a/src/awx_plugins/interfaces/_temporary_private_licensing_api.py b/src/awx_plugins/interfaces/_temporary_private_licensing_api.py index 7bfb7bf3..520fbc0f 100644 --- a/src/awx_plugins/interfaces/_temporary_private_licensing_api.py +++ b/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',