Various documentation improvements

- Hide special members
- Use intersphinx to link Python and Pydantic docs
- Fix documentation of type aliases (mostly)

Author: Syndace

docs/conf.py

@@ -37,9 +37,14 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints"
 ]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None)
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = [ "_templates" ]
 
@@ -61,29 +66,36 @@
 
 # -- Autodoc Configuration ---------------------------------------------------------------
 
-# The following two options seem to be ignored...
+nitpicky = True
+
 autodoc_typehints = "description"
-autodoc_type_aliases = { type_alias: f"{type_alias}" for type_alias in {
-    "Priv",
-    "Seed",
+autodoc_type_aliases = { k: k for k in {
+    "JSONType",
     "Ed25519Pub",
-    "JSONType"
+    "Priv",
+    "Seed"
 } }
 
+# https://github.com/sphinx-doc/sphinx/issues/10785
+def resolve_type_aliases(app, env, node, contnode):
+    """Resolve :class: references to our type aliases as :attr: instead."""
+    if (
+        node["refdomain"] == "py"
+        and node["reftype"] == "class"
+        and node["reftarget"] in autodoc_type_aliases
+    ):
+        return app.env.get_domain("py").resolve_xref(
+            env, node["refdoc"], app.builder, "attr", node["reftarget"], node, contnode
+        )
+
 def autodoc_skip_member_handler(app, what, name, obj, skip, options):
     # Skip private members, i.e. those that start with double underscores but do not end in underscores
     if name.startswith("__") and not name.endswith("_"):
         return True
 
-    # Could be achieved using exclude-members, but this is more comfy
-    if name in {
-        "__abstractmethods__",
-        "__dict__",
-        "__module__",
-        "__new__",
-        "__weakref__",
-        "_abc_impl"
-    }: return True
+    # Other fixed names to always skip
+    if name in { "_abc_impl" }:
+        return True
 
     # Skip __init__s without documentation. Those are just used for type hints.
     if name == "__init__" and obj.__doc__ is None:
@@ -93,3 +105,4 @@ def autodoc_skip_member_handler(app, what, name, obj, skip, options):
 
 def setup(app):
     app.connect("autodoc-skip-member", autodoc_skip_member_handler)
+    app.connect("missing-reference", resolve_type_aliases)

docs/omemo/backend.rst

@@ -3,7 +3,7 @@ Module: backend
 
 .. automodule:: omemo.backend
     :members:
-    :special-members:
+    :special-members: __init__
     :private-members:
     :undoc-members:
     :member-order: bysource

docs/omemo/bundle.rst

@@ -3,7 +3,7 @@ Module: bundle
 
 .. automodule:: omemo.bundle
     :members:
-    :special-members:
+    :special-members: __eq__, __hash__
     :private-members:
     :undoc-members:
     :member-order: bysource

docs/omemo/identity_key_pair.rst

@@ -3,7 +3,7 @@ Module: identity_key_pair
 
 .. automodule:: omemo.identity_key_pair
     :members:
-    :special-members:
+    :special-members: __init__
     :private-members:
     :undoc-members:
     :member-order: bysource

docs/omemo/session_manager.rst

@@ -3,7 +3,7 @@ Module: session_manager
 
 .. automodule:: omemo.session_manager
     :members:
-    :special-members:
+    :special-members: __init__
     :private-members:
     :undoc-members:
     :member-order: bysource

docs/omemo/storage.rst

@@ -8,3 +8,5 @@ Module: storage
     :undoc-members:
     :member-order: bysource
     :show-inheritance:
+
+.. autoclass:: omemo.storage.ValueTypeT

docs/omemo/types.rst

@@ -6,3 +6,8 @@ Module: types
     :undoc-members:
     :member-order: bysource
     :show-inheritance:
+
+Type Aliases
+============
+
+.. autoclass:: omemo.types.JSONType

omemo/__init__.py

@@ -41,6 +41,7 @@
     DeviceListDownloadFailed as DeviceListDownloadFailed,
     MessageSendingFailed as MessageSendingFailed,
 
+    EncryptionError as EncryptionError,
     SessionManager as SessionManager
 )
 

omemo/backend.py

@@ -296,7 +296,8 @@ async def decrypt_plaintext(self, content: Content, plain_key_material: PlainKey
         Decrypt some symmetrically encrypted plaintext.
 
         Args:
-            content: The content to decrypt. Not empty, i.e. :attr:`Content.empty` will return ``False``.
+            content: The content to decrypt. Not empty, i.e. :attr:`~omemo.message.Content.empty` will return
+                ``False``.
             plain_key_material: The key material to decrypt with.
 
         Returns:

omemo/identity_key_pair.py

@@ -1,20 +1,22 @@
-# This import from future (theoretically) enables sphinx_autodoc_typehints to handle type aliases better
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
 import logging
 import secrets
 
-import xeddsa.bindings as xeddsa
-from xeddsa.bindings import Ed25519Pub, Priv, Seed
+import xeddsa
+from xeddsa import Ed25519Pub, Priv, Seed
 
 from .storage import NothingException, Storage
 
 
 __all__ = [
     "IdentityKeyPair",
     "IdentityKeyPairPriv",
-    "IdentityKeyPairSeed"
+    "IdentityKeyPairSeed",
+    "Ed25519Pub",
+    "Priv",
+    "Seed"
 ]