commit 4f55589f837db2e7a5d4bf7b3e971780fb0eaa5c Author: Damian Johnson <atagar@torproject.org> Date: Sat May 16 17:33:01 2020 -0700 Add Sphinx sphinx_autodoc_typehints plugin Our methods document parater types twice... def my_method(my_arg: str) => None: """ Dummy method. :param str my_arg: sample argument """ The method signature and :param: reStructured tag both cite our my_arg type. By using Sphinx's sphinx_autodoc_typehints plugin we can drop our parameter types... https://github.com/agronholm/sphinx-autodoc-typehints Deduplication aside this makes our API docs look nicer by stripping Python type hints from our signatures. In other words... stem.util.system.is_available(command: str, cached: bool = True) → bool Parameters: command (str) -- command to search for cached (bool) -- makes use of available cached results if True ... becomes... stem.util.system.is_available(command, cached=True) Parameters: command (str) -- command to search for cached (bool) -- makes use of available cached results if True --- docs/conf.py | 32 ++++++++++++++++++++++++++++++-- stem/manual.py | 6 +++--- 2 files changed, 33 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index b880b114..f9aa73fc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,9 +11,37 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +import os +import sys +import warnings + from sphinx.domains.python import PythonDomain +TYPEHINTS_REQUIRED = """\ +Building Stem's website requires... + + https://github.com/agronholm/sphinx-autodoc-typehints + +Please run... + + % pip install sphinx-autodoc-typehints +""" + +try: + import sphinx_autodoc_typehints +except ImportError: + print(TYPEHINTS_REQUIRED, file = sys.stderr) + sys.exit(1) + +# These warnings are due to: https://github.com/agronholm/sphinx-autodoc-typehints/issues/133 + +warnings.filterwarnings('ignore', message = 'sphinx.util.inspect.Signature\(\) is deprecated') + +# Drop redundant return types because we state this in our :returns: clasuses. +# This is an argument for sphinx-autodoc-typehints. + +typehints_document_rtype = False + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -27,7 +55,7 @@ needs_sphinx = '1.1' # required for the sphinx-apidoc command # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'roles'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_autodoc_typehints', 'roles'] autodoc_default_options = { 'members': True, diff --git a/stem/manual.py b/stem/manual.py index 9bc10b85..a5d3ebef 100644 --- a/stem/manual.py +++ b/stem/manual.py @@ -64,7 +64,7 @@ import stem.util.log import stem.util.str_tools import stem.util.system -from typing import Any, Dict, IO, List, Mapping, Optional, Sequence, Tuple, Union +from typing import Any, BinaryIO, Dict, List, Mapping, Optional, Sequence, Tuple, Union Category = stem.util.enum.Enum('GENERAL', 'CLIENT', 'RELAY', 'DIRECTORY', 'AUTHORITY', 'HIDDEN_SERVICE', 'DENIAL_OF_SERVICE', 'TESTING', 'UNKNOWN') GITWEB_MANUAL_URL = 'https://gitweb.torproject.org/tor.git/plain/doc/tor.1.txt' @@ -265,7 +265,7 @@ def is_important(option: str) -> bool: return option.lower() in _config()['manual.important'] -def download_man_page(path: Optional[str] = None, file_handle: Optional[IO[bytes]] = None, url: str = GITWEB_MANUAL_URL, timeout: int = 20) -> None: +def download_man_page(path: Optional[str] = None, file_handle: Optional[BinaryIO] = None, url: str = GITWEB_MANUAL_URL, timeout: int = 20) -> None: """ Downloads tor's latest man page from `gitweb.torproject.org <https://gitweb.torproject.org/tor.git/plain/doc/tor.1.txt>`_. This method is @@ -501,7 +501,7 @@ class Manual(object): """ with tempfile.NamedTemporaryFile() as tmp: - download_man_page(file_handle = tmp, timeout = timeout) + download_man_page(file_handle = tmp, timeout = timeout) # type: ignore return Manual.from_man(tmp.name) def save(self, path: str) -> None: