[tor-commits] [stem/master] Add Sphinx sphinx_autodoc_typehints plugin

[atagar at torproject.org]

commit 4f55589f837db2e7a5d4bf7b3e971780fb0eaa5c
Author: Damian Johnson <atagar at 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: