From 235f83fdbe8a4ee081a0944cc59338f689bfe5dd Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Wed, 20 Nov 2024 18:12:05 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=A7=AA=F0=9F=93=9D=20Integrate=20`sphinx?= =?UTF-8?q?=5Fautodoc=5Ftypehints`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This allows dropping types from param lists in favor of annotations. --- .darglint | 2 +- bin/pip_constraint_helpers.py | 6 ------ bin/pip_wrapper.py | 3 --- bin/print_lockfile_base_name.py | 1 - bin/resolve_platform_lock_file.py | 6 ++---- dependencies/direct/build-docs.in | 1 + docs/_ext/spelling_stub_ext.py | 1 - docs/conf.py | 15 +++++++++++++++ 8 files changed, 19 insertions(+), 16 deletions(-) diff --git a/.darglint b/.darglint index 1991e0f718..927493c69a 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 47a99b8497..86721b5dbd 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 c5467a3dd7..2ccedc4b1f 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 272b43b0a7..09e67dae8f 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 95a0953cf9..565ca0833e 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 620d0bc940..e4d3207b60 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 2835fdac9c..e16d121386 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 d219194bf4..506da03ba6 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', @@ -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 = []