wip: typedef directive

Author: rickeylev

sphinxdocs/docs/sphinx-bzl.md

@@ -255,3 +255,28 @@ My docs
 Documents a flag. It has the same format as `{bzl:target}`
 :::
 
+
+:::{rst:directive} .. bzl:typedef:: typename
+
+Documents a user-defined structural "type".  These are typically generated
+by following [User-defined types] to create a struct with a `TYPEDEF` field.
+
+```
+::::{bzl:typedef} Square
+
+:::{bzl:field} width
+:type: int
+:::
+
+:::{bzl:function} new(size)
+:::
+
+:::{bzl:function} area()
+:::
+::::
+```
+
+Note that, due to a Sphinx and/or MyST bug, the number of colons for the
+outer typedef directive must be greater than the inner directives. Otherwise,
+only the first nested directive is parsed as part of the type def.
+:::

sphinxdocs/docs/starlark-docgen.md

@@ -73,3 +73,86 @@ bzl_library(
    deps = ...
 )
 ```
+
+## User-defined types
+
+While Starlark doesn't have user-defined types as a first-class concept, it's
+still possible to create such objects using `struct` and lambdas. For the
+purposes of documentation, they can be documented by creating a module-level
+`struct` with matching fields *and* also a field named `TYPEDEF`. When the
+`sphinx_stardoc` rule sees a struct with a `TYPEDEF` field, it generates doc
+using the {rst:directive}`bzl:typedef` directive and puts all the struct's fields
+within the typedef. The net result is the rendered docs look similar to how
+a class would be documented in other programming languages.
+
+For example, a `Square` object with a `area()` method would look like:
+
+```
+
+def _Square_typedef():
+    """A square with fixed size.
+
+    :::{field} width
+    :type: int
+    :::
+    """
+
+def _Square_new(width):
+    """Creates a Square.
+
+    Args:
+        width: {type}`int` width of square
+
+    Returns:
+        {type}`Square`
+    """
+    self = struct(
+        area = lambda *a, **k: _Square_area(self, *a, **k),
+        width = width
+    )
+    return self
+
+def _Square_area(self, ):
+   """Tells the area of the square."""
+   return self.width * self.width
+
+Square = struct(
+  TYPEDEF = _Square_typedef,
+  new = _Square_new,
+  area = _Square_area,
+)
+```
+
+This will then genereate markdown that looks like:
+
+```
+::::{bzl:typedef} Square
+A square with fixed size
+
+:::{bzl:field} width
+:type: int
+:::
+:::{bzl:function} new()
+...
+:::
+:::{bzl:function} area()
+...
+:::
+::::
+```
+
+Which renders as:
+
+::::{bzl:typedef} Square
+A square with fixed size
+
+:::{bzl:field} width
+:type: int
+:::
+:::{bzl:function} new()
+...
+:::
+:::{bzl:function} area()
+...
+:::
+::::

sphinxdocs/private/proto_to_markdown.py

@@ -96,6 +96,15 @@ def __init__(
         self._module = module
         self._out_stream = out_stream
         self._public_load_path = public_load_path
+        self._typedef_stack = []
+
+    def _get_colons(self):
+        # There's a weird behavior where increasing colon indents doesn't
+        # parse as nested objects correctly, so we have to reduce the
+        # number of colons based on the indent level
+        indent = 10 - len(self._typedef_stack)
+        assert indent >= 0
+        return ":::" + ":" * indent
 
     def render(self):
         self._render_module(self._module)
@@ -115,11 +124,10 @@ def _render_module(self, module: stardoc_output_pb2.ModuleInfo):
             "\n\n",
         )
 
-        # Sort the objects by name
         objects = itertools.chain(
             ((r.rule_name, r, self._render_rule) for r in module.rule_info),
             ((p.provider_name, p, self._render_provider) for p in module.provider_info),
-            ((f.function_name, f, self._render_func) for f in module.func_info),
+            ((f.function_name, f, self._process_func_info) for f in module.func_info),
             ((a.aspect_name, a, self._render_aspect) for a in module.aspect_info),
             (
                 (m.extension_name, m, self._render_module_extension)
@@ -130,13 +138,31 @@ def _render_module(self, module: stardoc_output_pb2.ModuleInfo):
                 for r in module.repository_rule_info
             ),
         )
+        # Sort by name, ignoring case. The `.TYPEDEF` string is removed so
+        # that the .TYPEDEF entries come before what is in the typedef.
+        objects = sorted(objects, key=lambda v: v[0].removesuffix(".TYPEDEF").lower())
 
-        objects = sorted(objects, key=lambda v: v[0].lower())
-
-        for _, obj, func in objects:
-            func(obj)
+        for name, obj, func in objects:
+            self._process_object(name, obj, func)
             self._write("\n")
 
+        # Close any typedefs
+        while self._typedef_stack:
+            self._typedef_stack.pop()
+            self._render_typedef_end()
+
+    def _process_object(self, name, obj, renderer):
+        # The trailing doc is added to prevent matching a common prefix
+        typedef_group = name.removesuffix(".TYPEDEF") + "."
+        while self._typedef_stack and not typedef_group.startswith(
+            self._typedef_stack[-1]
+        ):
+            self._typedef_stack.pop()
+            self._render_typedef_end()
+        renderer(obj)
+        if name.endswith(".TYPEDEF"):
+            self._typedef_stack.append(typedef_group)
+
     def _render_aspect(self, aspect: stardoc_output_pb2.AspectInfo):
         _sort_attributes_inplace(aspect.attribute)
         self._write("::::::{bzl:aspect} ", aspect.aspect_name, "\n\n")
@@ -242,12 +268,32 @@ def _rule_attr_type_string(self, attr: stardoc_output_pb2.AttributeInfo) -> str:
             # Rather than error, give some somewhat understandable value.
             return _AttributeType.Name(attr.type)
 
+    def _process_func_info(self, func):
+        if func.function_name.endswith(".TYPEDEF"):
+            self._render_typedef_start(func)
+        else:
+            self._render_func(func)
+
+    def _render_typedef_start(self, func):
+        self._write(
+            self._get_colons(),
+            "{bzl:typedef} ",
+            func.function_name.removesuffix(".TYPEDEF"),
+            "\n",
+        )
+        if func.doc_string:
+            self._write(func.doc_string.strip(), "\n")
+
+    def _render_typedef_end(self):
+        self._write(self._get_colons(), "\n\n")
+
     def _render_func(self, func: stardoc_output_pb2.StarlarkFunctionInfo):
-        self._write("::::::{bzl:function} ")
+        self._write(self._get_colons(), "{bzl:function} ")
 
         parameters = self._render_func_signature(func)
 
-        self._write(func.doc_string.strip(), "\n\n")
+        if doc_string := func.doc_string.strip():
+            self._write(doc_string, "\n\n")
 
         if parameters:
             for param in parameters:
@@ -268,10 +314,13 @@ def _render_func(self, func: stardoc_output_pb2.StarlarkFunctionInfo):
             self._write(":::::{deprecated}: unknown\n")
             self._write("  ", _indent_block_text(func.deprecated.doc_string), "\n")
             self._write(":::::\n")
-        self._write("::::::\n")
+        self._write(self._get_colons(), "\n")
 
     def _render_func_signature(self, func):
-        self._write(f"{func.function_name}(")
+        func_name = func.function_name
+        if self._typedef_stack:
+            func_name = func.function_name.removeprefix(self._typedef_stack[-1])
+        self._write(f"{func_name}(")
         # TODO: Have an "is method" directive in the docstring to decide if
         # the self parameter should be removed.
         parameters = [param for param in func.parameter if param.name != "self"]

sphinxdocs/src/sphinx_bzl/bzl.py

@@ -424,7 +424,7 @@ def _make_xrefs_for_arg_attr(
         return [wrapper]
 
 
-class _BzlField(_BzlXrefField, docfields.Field):
+class _BzlDocField(_BzlXrefField, docfields.Field):
     """A non-repeated field with xref support."""
 
 
@@ -623,6 +623,7 @@ def handle_signature(
         relative_name = relative_name.strip()
 
         name_prefix, _, base_symbol_name = relative_name.rpartition(".")
+
         if name_prefix:
             # Respect whatever the signature wanted
             display_prefix = name_prefix
@@ -819,6 +820,26 @@ class _BzlCallable(_BzlObject):
     """Abstract base class for objects that are callable."""
 
 
+class _BzlTypedef(_BzlObject):
+    """Documents a typedef.
+
+    A typedef describes objects with well known attributes.
+
+    ::::{bzl:typedef} Square
+
+    :::{bzl:field} width
+    :type: int
+    :::
+
+    :::{bzl:function} new(size)
+    :::
+
+    :::{bzl:function} area()
+    :::
+    ::::
+    """
+
+
 class _BzlProvider(_BzlObject):
     """Documents a provider type.
 
@@ -837,7 +858,7 @@ class _BzlProvider(_BzlObject):
     """
 
 
-class _BzlProviderField(_BzlObject):
+class _BzlField(_BzlObject):
     """Documents a field of a provider.
 
     Fields can optionally have a type specified using the `:type:` option.
@@ -872,6 +893,10 @@ def _get_alt_names(self, object_entry):
         return alt_names
 
 
+class _BzlProviderField(_BzlField):
+    pass
+
+
 class _BzlRepositoryRule(_BzlCallable):
     """Documents a repository rule.
 
@@ -951,7 +976,7 @@ class _BzlRule(_BzlCallable):
             rolename="attr",
             can_collapse=False,
         ),
-        _BzlField(
+        _BzlDocField(
             "provides",
             label="Provides",
             has_arg=False,
@@ -1078,13 +1103,13 @@ class _BzlModuleExtension(_BzlObject):
     """
 
     doc_field_types = [
-        _BzlField(
+        _BzlDocField(
             "os-dependent",
             label="OS Dependent",
             has_arg=False,
             names=["os-dependent"],
         ),
-        _BzlField(
+        _BzlDocField(
             "arch-dependent",
             label="Arch Dependent",
             has_arg=False,
@@ -1448,7 +1473,8 @@ class _BzlDomain(domains.Domain):
         # Providers are close enough to types that we include "type". This
         # also makes :type: Foo work in directive options.
         "provider": domains.ObjType("provider", "provider", "type", "obj"),
-        "provider-field": domains.ObjType("provider field", "field", "obj"),
+        "provider-field": domains.ObjType("provider field", "provider-field", "obj"),
+        "field": domains.ObjType("field", "field", "obj"),
         "repo-rule": domains.ObjType("repository rule", "repo_rule", "obj"),
         "rule": domains.ObjType("rule", "rule", "obj"),
         "tag-class": domains.ObjType("tag class", "tag_class", "obj"),
@@ -1457,6 +1483,7 @@ class _BzlDomain(domains.Domain):
         "flag": domains.ObjType("flag", "flag", "target", "obj"),
         # types are objects that have a constructor and methods/attrs
         "type": domains.ObjType("type", "type", "obj"),
+        "typedef": domains.ObjType("typedef", "typedef", "type", "obj"),
     }
 
     # This controls:
@@ -1483,7 +1510,9 @@ class _BzlDomain(domains.Domain):
         "function": _BzlFunction,
         "module-extension": _BzlModuleExtension,
         "provider": _BzlProvider,
+        "typedef": _BzlTypedef,
         "provider-field": _BzlProviderField,
+        "field": _BzlField,
         "repo-rule": _BzlRepositoryRule,
         "rule": _BzlRule,
         "tag-class": _BzlTagClass,

sphinxdocs/tests/proto_to_markdown/proto_to_markdown_test.py

@@ -193,6 +193,22 @@ def test_render_signature(self):
         self.assertIn('{default-value}`"@repo//pkg:file.bzl"`', actual)
         self.assertIn("{default-value}`'<function foo from //bar:baz.bzl>'", actual)
 
+    def test_render_typedefs(self):
+        proto_text = """
+file: "@repo//pkg:foo.bzl"
+func_info: { function_name: "Zeta.TYPEDEF" }
+func_info: { function_name: "Carl.TYPEDEF" }
+func_info: { function_name: "Carl.ns.Alpha.TYPEDEF" }
+func_info: { function_name: "Beta.TYPEDEF" }
+func_info: { function_name: "Beta.Sub.TYPEDEF" }
+"""
+        actual = self._render(proto_text)
+        self.assertIn("\n:::::::::::::{bzl:typedef} Beta\n", actual)
+        self.assertIn("\n::::::::::::{bzl:typedef} Beta.Sub\n", actual)
+        self.assertIn("\n:::::::::::::{bzl:typedef} Carl\n", actual)
+        self.assertIn("\n::::::::::::{bzl:typedef} Carl.ns.Alpha\n", actual)
+        self.assertIn("\n:::::::::::::{bzl:typedef} Zeta\n", actual)
+
 
 if __name__ == "__main__":
     absltest.main()

sphinxdocs/tests/sphinx_stardoc/BUILD.bazel

@@ -42,7 +42,10 @@ sphinx_docs(
 
 sphinx_stardocs(
     name = "simple_bzl_docs",
-    srcs = [":bzl_rule_bzl"],
+    srcs = [
+        ":bzl_rule_bzl",
+        ":bzl_typedef_bzl",
+    ],
     target_compatible_with = _TARGET_COMPATIBLE_WITH,
 )
 
@@ -76,6 +79,11 @@ bzl_library(
     deps = [":func_and_providers_bzl"],
 )
 
+bzl_library(
+    name = "bzl_typedef_bzl",
+    srcs = ["bzl_typedef.bzl"],
+)
+
 sphinx_build_binary(
     name = "sphinx-build",
     tags = ["manual"],  # Only needed as part of sphinx doc building