doc: make Signer docstrings sphinx-friendly

- re-format Signer and Key docstrings
- add autodoc docstrings for public dispatch tables
- add args docstrings for Signature

Signed-off-by: Lukas Puehringer <[email protected]>

securesystemslib/signer/_key.py

@@ -56,6 +56,11 @@
 # NOTE Key dispatch table is defined here so it's usable by Key,
 # but is populated in __init__.py (and can be appended by users).
 KEY_FOR_TYPE_AND_SCHEME: Dict[Tuple[str, str], Type] = {}
+"""Key dispatch table for ``Key.from_dict()``
+
+See ``securesystemslib.signer.KEY_FOR_TYPE_AND_SCHEME`` for default key types
+and schemes, and how to register custom implementations.
+"""
 
 
 class Key(metaclass=ABCMeta):
@@ -121,8 +126,9 @@ def from_dict(cls, keyid: str, key_dict: Dict[str, Any]) -> "Key":
         Key implementations must override this factory constructor that is used
         as a deserialization helper.
 
-        Users should call Key.from_dict(): it dispatches to the actual subclass
-        implementation based on supported keys in KEY_FOR_TYPE_AND_SCHEME.
+        Users should call ``Key.from_dict()``: it dispatches to the actual
+        subclass implementation based on supported keys in
+        ``KEY_FOR_TYPE_AND_SCHEME``.
 
         Raises:
             KeyError, TypeError: Invalid arguments.

securesystemslib/signer/_signature.py

@@ -15,6 +15,12 @@ class Signature:
     Provides utility methods to easily create an object from a dictionary
     and return the dictionary representation of the object.
 
+    Args:
+        keyid: HEX string used as a unique identifier of the key.
+        sig: HEX string representing the signature.
+        unrecognized_fields: Dictionary of all attributes that are not managed
+            by securesystemslib.
+
     Attributes:
         keyid: HEX string used as a unique identifier of the key.
         signature: HEX string representing the signature.

securesystemslib/signer/_signer.py

@@ -12,7 +12,11 @@
 # NOTE Signer dispatch table is defined here so it's usable by Signer,
 # but is populated in __init__.py (and can be appended by users).
 SIGNER_FOR_URI_SCHEME: Dict[str, Type] = {}
+"""Signer dispatch table for ``Signer.from_priv_key()``
 
+See ``securesystemslib.signer.SIGNER_FOR_URI_SCHEME`` for default URI schemes,
+and how to register custom implementations.
+"""
 
 # SecretsHandler is a function the calling code can provide to Signer:
 # SecretsHandler will be called if Signer needs additional secrets.
@@ -24,23 +28,25 @@
 class Signer(metaclass=ABCMeta):
     """Signer interface that supports multiple signing implementations.
 
-    Usage example:
+    Usage example::
 
         signer = Signer.from_priv_key_uri("envvar:MYPRIVKEY", pub_key)
         sig = signer.sign(b"data")
 
     Note that signer implementations may raise errors (during both
-    Signer.from_priv_key_uri() and Signer.sign()) that are not documented here:
-    examples could include network errors or file read errors. Applications
-    should use generic try-except here if unexpected raises are not an option.
+    ``Signer.from_priv_key_uri()`` and ``Signer.sign()``) that are not
+    documented here: examples could include network errors or file read errors.
+    Applications should use generic try-except here if unexpected raises are
+    not an option.
 
-    See SIGNER_FOR_URI_SCHEME for supported private key URI schemes. The
+    See ``SIGNER_FOR_URI_SCHEME`` for supported private key URI schemes. The
     currently supported default schemes are:
-    * envvar: see SSlibSigner for details
-    * file: see SSlibSigner for details
+
+    * envvar: see ``SSlibSigner`` for details
+    * file: see ``SSlibSigner`` for details
 
     Interactive applications may also define a secrets handler that allows
-    asking for user secrets if they are needed:
+    asking for user secrets if they are needed::
 
         from getpass import getpass
 
@@ -55,7 +61,7 @@ def sec_handler(secret_name:str) -> str:
         uri2 = "file:keys/myenckey?encrypted=true"
         signer2 = Signer.from_priv_key_uri(uri2, pub_key2, sec_handler)
 
-    Applications can provide their own Signer and Key implementations:
+    Applications can provide their own Signer and Key implementations::
 
         from securesystemslib.signer import Signer, SIGNER_FOR_URI_SCHEME
         from mylib import MySigner
@@ -90,7 +96,7 @@ def from_priv_key_uri(
         """Factory constructor for a given private key URI
 
         Returns a specific Signer instance based on the private key URI and the
-        supported uri schemes listed in SIGNER_FOR_URI_SCHEME.
+        supported uri schemes listed in ``SIGNER_FOR_URI_SCHEME``.
 
         Args:
             priv_key_uri: URI that identifies the private key