improve docs

docs/conf.py

@@ -33,7 +33,13 @@
 # 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_rtd_theme", "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.autosectionlabel"]
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.intersphinx",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -58,3 +64,8 @@
 version = "3.0.4"
 
 master_doc = "index"
+
+# Looks for objects in external projects
+intersphinx_mapping = {
+    "grpc": ("https://grpc.github.io/grpc/python/", None),
+}

docs/errors.rst

@@ -44,6 +44,8 @@ All ``pyzeebe`` errors inherit from :py:class:`PyZeebeError`
 
 .. autoexception:: pyzeebe.errors.InvalidCamundaCloudCredentialsError
 
+.. autoexception:: pyzeebe.errors.UnkownGrpcStatusCodeError
+
 
 =================
 Exception Handler

pyzeebe/credentials/base.py

@@ -4,7 +4,7 @@
 
 
 class CredentialsABC(abc.ABC):
-    """TODO."""
+    """A specification for credentials manager. Passed to :py:class:`AuthMetadataPlugin`."""
 
     @abc.abstractmethod
     def get_auth_metadata(self, context: CallContext) -> AuthMetadata:
@@ -13,6 +13,6 @@ def get_auth_metadata(self, context: CallContext) -> AuthMetadata:
             context (grpc.AuthMetadataContext): Provides information to call credentials metadata plugins.
 
         Returns:
-            Tuple[Tuple[str, Union[str, bytes]], ...]: The `metadata` used to construct the grpc.CallCredentials.
+            Tuple[Tuple[str, Union[str, bytes]], ...]: The `metadata` used to construct the :py:class:`grpc.CallCredentials`.
         """
         raise NotImplementedError

pyzeebe/credentials/camunda_identity.py

@@ -16,8 +16,8 @@ class CamundaIdentityCredentials(CredentialsABC):
         oauth_url (str): The Keycloak auth endpoint url.
         client_id (str): The client id provided by Camunda Platform
         client_secret (str): The client secret provided by Camunda Platform
-        audience (str):
-        refresh_threshold_seconds (int):
+        audience (str): Audience for Zeebe. Default: zeebe-api
+        refresh_threshold_seconds (int): Will try to refresh token if it expires in this number of seconds or less. Default: 20
     """
 
     def __init__(
@@ -75,7 +75,7 @@ def get_auth_metadata(self, context: CallContext) -> AuthMetadata:
             context (grpc.AuthMetadataContext): Provides information to call credentials metadata plugins.
 
         Returns:
-            Tuple[Tuple[str, Union[str, bytes]], ...]: The `metadata` used to construct the grpc.CallCredentials.
+            Tuple[Tuple[str, Union[str, bytes]], ...]: The `metadata` used to construct the :py:class:`grpc.CallCredentials`.
 
         Raises:
             InvalidOAuthCredentialsError: One of the provided camunda credentials is not correct

pyzeebe/credentials/plugins.py

@@ -7,10 +7,10 @@
 
 
 class AuthMetadataPlugin(grpc.AuthMetadataPlugin):
-    """TODO.
+    """Custom authentication plugin with exception catching.
 
     Args:
-        credentials (CredentialsABC): TODO
+        credentials (CredentialsABC): A credentials manager.
     """
 
     def __init__(self, *, credentials: CredentialsABC) -> None:
@@ -30,11 +30,6 @@ def __call__(self, context: grpc.AuthMetadataContext, callback: grpc.AuthMetadat
         try:
             metadata = self._credentials.get_auth_metadata(context)
         except Exception as e:
-            self._sign_request(callback, (), e)
+            callback((), e)
         else:
-            self._sign_request(callback, metadata, None)
-
-    def _sign_request(
-        self, callback: grpc.AuthMetadataPluginCallback, metadata: AuthMetadata, error: Optional[Exception]
-    ) -> None:
-        callback(metadata, error)
+            callback(metadata, None)