Add documentation for KerasRS embedding layers. (#2106)

Also
- update Keras version to 3.10.0
- augment `docstring.py` to support function signatures where the default value of an argument is a Keras object.
- add support for `dataclass` classes where `__init__` is injected dynamically.

Author: hertschuh

scripts/autogen.py

@@ -32,7 +32,7 @@
 GUIDES_GH_LOCATION = Path("keras-team") / "keras-io" / "blob" / "master" / "guides"
 KERAS_TEAM_GH = "https://github.com/keras-team"
 PROJECT_URL = {
-    "keras": f"{KERAS_TEAM_GH}/keras/tree/v3.9.2/",
+    "keras": f"{KERAS_TEAM_GH}/keras/tree/v3.10.0/",
     "keras_tuner": f"{KERAS_TEAM_GH}/keras-tuner/tree/v1.4.7/",
     "keras_hub": f"{KERAS_TEAM_GH}/keras-hub/tree/v0.20.0/",
     "tf_keras": f"{KERAS_TEAM_GH}/tf-keras/tree/v2.19.0/",

scripts/docstrings.py

@@ -188,6 +188,64 @@ def get_function_name(function):
     return function.__name__
 
 
+def get_default_value_for_repr(value):
+    """Return a substitute for rendering the default value of a funciton arg.
+
+    Function and object instances are rendered as <Foo object at 0x00000000>
+    which can't be parsed by black. We substitute functions with the function
+    name and objects with a rendered version of the constructor like
+    `Foo(a=2, b="bar")`.
+
+    Args:
+        value: The value to find a better rendering of.
+
+    Returns:
+        Another value or `None` if no substitution is needed.
+    """
+
+    class ReprWrapper:
+        def __init__(self, representation):
+            self.representation = representation
+
+        def __repr__(self):
+            return self.representation
+
+    if value is inspect._empty:
+        return None
+
+    if inspect.isfunction(value):
+        # Render the function name instead
+        return ReprWrapper(value.__name__)
+
+    if (
+        repr(value).startswith("<")  # <Foo object at 0x00000000>
+        and hasattr(value, "__class__")  # it is an object
+        and hasattr(value, "get_config")  # it is a Keras object
+    ):
+        config = value.get_config()
+        init_args = []  # The __init__ arguments to render
+        for p in inspect.signature(value.__class__.__init__).parameters.values():
+            if p.name == "self":
+                continue
+            if p.kind == inspect.Parameter.POSITIONAL_ONLY:
+                # Required positional, render without a name
+                init_args.append(repr(config[p.name]))
+            elif p.default is inspect._empty or p.default != config[p.name]:
+                # Keyword arg with non-default value, render
+                init_args.append(p.name + "=" + repr(config[p.name]))
+            # else don't render that argument
+        return ReprWrapper(
+            value.__class__.__module__
+            + "."
+            + value.__class__.__name__
+            + "("
+            + ", ".join(init_args)
+            + ")"
+        )
+
+    return None
+
+
 def get_signature_start(function):
     """For the Dense layer, it should return the string 'keras.layers.Dense'"""
     if ismethod(function):
@@ -209,9 +267,12 @@ def get_signature_end(function):
 
     formatted_params = []
     for x in params:
+        default = get_default_value_for_repr(x.default)
+        if default:
+            x = inspect.Parameter(
+                x.name, x.kind, default=default, annotation=x.annotation
+            )
         str_x = str(x)
-        if "<function" in str_x:
-            str_x = re.sub(r'<function (.*?) at 0x[0-9a-fA-F]+>', r'\1', str_x)
         formatted_params.append(str_x)
     signature_end = "(" + ", ".join(formatted_params) + ")"
 
@@ -382,10 +443,8 @@ def get_class_from_method(meth):
                 return cls
         meth = meth.__func__  # fallback to __qualname__ parsing
     if inspect.isfunction(meth):
-        cls = getattr(
-            inspect.getmodule(meth),
-            meth.__qualname__.split(".<locals>", 1)[0].rsplit(".", 1)[0],
-        )
+        cls_name = meth.__qualname__.split(".<locals>", 1)[0].rsplit(".", 1)[0]
+        cls = getattr(inspect.getmodule(meth), cls_name, None)
         if isinstance(cls, type):
             return cls
     return getattr(meth, "__objclass__", None)  # handle special descriptor objects

scripts/rs_master.py

@@ -81,29 +81,43 @@
     ]
 }
 
-# LAYERS_MASTER = {
-#     "path": "layers/",
-#     "title": "Layers",
-#     "toc": True,
-#     "children": [
-#         {
-#             "path": "distributed_embedding",
-#             "title": "DistributedEmbedding layer",
-#             "generate": [
-#                 "keras_rs.layers.DistributedEmbedding",
-#                 "keras_rs.layers.DistributedEmbedding.call",
-#             ],
-#         },
-#         {
-#             "path": "frequency_estimator",
-#             "title": "FrequencyEstimator layer",
-#             "generate": [
-#                 "keras_rs.layers.FrequencyEstimator",
-#                 "keras_rs.layers.FrequencyEstimator.call",
-#             ],
-#         },
-#     ]
-# }
+EMBEDDING_LAYERS_MASTER = {
+    "path": "embedding_layers/",
+    "title": "Embedding Layers",
+    "toc": True,
+    "children": [
+        {
+            "path": "distributed_embedding",
+            "title": "DistributedEmbedding layer",
+            "generate": [
+                "keras_rs.layers.DistributedEmbedding",
+                "keras_rs.layers.DistributedEmbedding.call",
+            ],
+        },
+        {
+            "path": "table_config",
+            "title": "TableConfig configuration class",
+            "generate": [
+                "keras_rs.layers.TableConfig",
+            ],
+        },
+        {
+            "path": "feature_config",
+            "title": "FeatureConfig configuration class",
+            "generate": [
+                "keras_rs.layers.FeatureConfig",
+            ],
+        },
+        {
+            "path": "embed_reduce",
+            "title": "EmbedReduce layer",
+            "generate": [
+                "keras_rs.layers.EmbedReduce",
+                "keras_rs.layers.EmbedReduce.call",
+            ],
+        },
+    ]
+}
 
 LOSSES_MASTER = {
     "path": "losses/",
@@ -194,7 +208,7 @@
     "title": "API documentation",
     "toc": True,
     "children": [
-        # LAYERS_MASTER,
+        EMBEDDING_LAYERS_MASTER,
         FEATURE_INTERACTION_LAYERS_MASTER,
         RETRIEVAL_LAYERS_MASTER,
         LOSSES_MASTER,