cleanup docs build process and add various improvements (#347)

Makefile

@@ -107,6 +107,7 @@ livedocs:
 
 clean-docs:
 	-rm -rf "$(SPHINX_BUILDDIR)"
+	-rm -rf "$(DOCUMENTATION)"
 
 lint: flakecheck apicheck configcheck readmecheck pep257check vulture
 

docs/_ext/typehints.py

@@ -1,4 +1,5 @@
 import inspect
+import logging
 from typing import Any, AnyStr, TypeVar, get_type_hints
 try:
     from sphinx.ext.autodoc import Signature
@@ -127,10 +128,12 @@ def process_docstring(app, what, name, obj, options, lines):
         obj = inspect.unwrap(obj)
         try:
             type_hints = get_type_hints(obj)
-        # except (AttributeError, TypeError):
-        except:  # FIXME: A new exception is being raised, likely due to upgrading sphinx
+        except (AttributeError, TypeError):
             # Introspecting a slot wrapper will raise TypeError
             return
+        except Exception as e:  # FIXME: A new exception is being raised, likely due to upgrading sphinx
+            logging.exception(e)
+            return
 
         for argname, annotation in type_hints.items():
             formatted_annotation = format_annotation(annotation)

faust/stores/rocksdb.py

@@ -139,8 +139,14 @@ def as_options(self) -> Options:
 
 class Store(base.SerializedStore):
     """RocksDB table storage.
-    Pass 'options={'read_only': True}' as an option into a Table class
-    to allow a RocksDB store be used by multiple apps.
+
+    .. tip::
+        You can specify 'read_only' as an option into a Table class
+        to allow a RocksDB store be used by multiple apps::
+
+            app.App(..., store="rocksdb://")
+            app.GlobalTable(..., options={'read_only': True})
+
     """
 
     offset_key = b"__faust\0offset__"