Add support for classes to generated python common API index (#2401)

Classes such as `ClassDescription` and `AnnotationInfo` make up an
import part of the API surface for many rerun APIs. Add support for the
classes to `gen_common_index.py`.

TODO:
 - [ ] After landing, cherry-pick into release-0.6

Additional:
- set the heading_level for these generated components to 4, which
matches the styling from the full package index and results in better
TOC representation.
- Add the same template modification that we use from functions to
disable `first` so we get a continuity bar for the class rendering like
we do for functions.
 - Modify the CSS so that links are visible.

Previews:

![image](https://github.com/rerun-io/rerun/assets/3312232/ec0bd281-da4e-4a9a-886b-1689a41ea0ca)

![image](https://github.com/rerun-io/rerun/assets/3312232/3e48e72a-abef-408c-8731-18fead234679)

Related to: #2385
Closes: #2393

* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [ ] I've included a screenshot or gif (if applicable)

<!-- This line will get updated when the PR build summary job finishes.
-->
PR Build Summary: https://build.rerun.io/pr/2401

<!-- pr-link-docs:start -->
Docs preview: https://rerun.io/preview/b58a10c/docs
Examples preview: https://rerun.io/preview/b58a10c/examples
<!-- pr-link-docs:end -->

rerun_py/docs/css/mkdocstrings.css

@@ -39,7 +39,7 @@ body {
   color: inherit;
 }
 
-.md-typeset p + h1 {
+.md-typeset p+h1 {
   margin-top: 2rem;
 }
 
@@ -51,3 +51,7 @@ code {
   --md-code-bg-color: #e3e3e3;
   font-family: "JetBrains Mono", monospace;
 }
+
+.md-typeset a {
+  --md-typeset-a-color: #526cfe;
+}

rerun_py/docs/gen_common_index.py

@@ -38,8 +38,9 @@
 @dataclass
 class Section:
     title: str
-    module_summary: Optional[str]
-    func_list: List[str]
+    module_summary: str | None
+    func_list: list[str]
+    class_list: list[str]
 
 
 # This is the list of sections and functions that will be included in the index
@@ -49,16 +50,19 @@ class Section:
         title="Initialization",
         module_summary=None,
         func_list=["init", "connect", "disconnect", "spawn", "serve", "memory_recording"],
+        class_list=[],
     ),
     Section(
         title="Viewer Control",
         module_summary=None,
         func_list=["save"],
+        class_list=[],
     ),
     Section(
         title="Time",
         module_summary=None,
         func_list=["set_time_sequence", "set_time_seconds", "set_time_nanos"],
+        class_list=[],
     ),
     Section(
         title="Spatial Primitives",
@@ -76,58 +80,69 @@ class Section:
             "log_meshes",
             "log_mesh_file",
         ],
+        class_list=[],
     ),
     Section(
         title="Images",
         module_summary=None,
         func_list=["log_image", "log_image_file", "log_depth_image", "log_segmentation_image"],
+        class_list=[],
     ),
     Section(
         title="Tensors",
         module_summary=None,
         func_list=["log_tensor"],
+        class_list=[],
     ),
     Section(
         title="Annotations",
         module_summary=None,
         func_list=["log_annotation_context"],
+        class_list=["ClassDescription", "AnnotationInfo"],
     ),
     Section(
         title="Extension Components",
         module_summary=None,
         func_list=["log_extension_components"],
+        class_list=[],
     ),
     Section(
         title="Plotting",
         module_summary=None,
         func_list=["log_scalar"],
+        class_list=[],
     ),
     Section(
         title="Transforms",
         module_summary="log.transform",
         func_list=["log_rigid3", "log_pinhole", "log_unknown_transform", "log_view_coordinates"],
+        class_list=[],
     ),
     Section(
         title="Text",
         module_summary=None,
         # TODO(#1251): Classes aren't supported yet
         # "LogLevel", "LoggingHandler"
         func_list=["log_text_entry"],
+        class_list=["LogLevel", "LoggingHandler"],
     ),
     Section(
         title="Clearing Entities",
         module_summary=None,
         func_list=["log_cleared"],
+        class_list=[],
     ),
     Section(
         title="Helpers",
         module_summary="script_helpers",
         func_list=["script_add_args", "script_setup", "script_teardown"],
+        class_list=[],
     ),
     Section(
         title="Experimental",
         module_summary="experimental",
         func_list=["experimental.log_text_box"],
+        class_list=[],
     ),
 ]
 
@@ -199,14 +214,29 @@ def make_slug(s: str) -> str:
                 fd.write("----\n")
             for func_name in section.func_list:
                 fd.write(f"::: rerun.{func_name}\n")
+                fd.write("    options:\n")
+                fd.write("      heading_level: 4\n")
+            for class_name in section.class_list:
+                # fd.write(f"::: rerun.{class_name}\n")
+                fd.write(f"::: rerun.{class_name}\n")
+                fd.write("    options:\n")
+                fd.write("      heading_level: 4\n")
 
         # Write out a table for the section in the index_file
         index_file.write(f"## {section.title}\n")
-        index_file.write("Function | Description\n")
-        index_file.write("-------- | -----------\n")
-        for func_name in section.func_list:
-            func = rerun_pkg[func_name]
-            index_file.write(f"[`rerun.{func_name}()`]({md_name}#rerun.{func_name}) | {func.docstring.lines[0]}\n")
+        if section.func_list:
+            index_file.write("Function | Description\n")
+            index_file.write("-------- | -----------\n")
+            for func_name in section.func_list:
+                func = rerun_pkg[func_name]
+                index_file.write(f"[`rerun.{func_name}()`]({md_name}#rerun.{func_name}) | {func.docstring.lines[0]}\n")
+        if section.class_list:
+            index_file.write("\n")
+            index_file.write("Class | Description\n")
+            index_file.write("-------- | -----------\n")
+            for class_name in section.class_list:
+                cls = rerun_pkg[class_name]
+                index_file.write(f"[`rerun.{class_name}`]({md_name}#rerun.{class_name}) | {cls.docstring.lines[0]}\n")
 
         index_file.write("\n")
 

rerun_py/docs/package/index.md

@@ -1,6 +1,6 @@
 # Full Package
 
-- [rerun][]: Top-level User-facing APIs. See also: [Common APIs](/common)
+- [rerun][]: Top-level User-facing APIs. See also: [Common APIs](../common/)
     - [rerun.log][]: APIs for logging data
     - [rerun.color_conversion][]: Conversion utilities related to colors
     - [rerun.components][]: Helpers for constructing arrow components

rerun_py/docs/templates/python/material/class.html

@@ -75,7 +75,10 @@
     {% set heading_level = heading_level - 1 %}
   {% endif %}
 
-  <div class="doc doc-contents {% if root %}first{% endif %}">
+  {# CHANGE Relative to Upstream: don't apply the 'first' class since it causes worse CSS formatting for our #}
+  {# generated common API index since we inline bare functions that become root-level rather than modules. #}
+  {#<div class="doc doc-contents {% if root %}first{% endif %}">#}
+  <div class="doc doc-contents">
     {% if config.show_bases and class.bases %}
       <p class="doc doc-class-bases">
         Bases: {% for expression in class.bases -%}

rerun_py/docs/templates/python/material/function.html

@@ -64,9 +64,10 @@
     {% set heading_level = heading_level - 1 %}
   {% endif %}
 
-  {# CHANGE: disable gating of first for root docstring #}
+  {# CHANGE Relative to Upstream: don't apply the 'first' class since it causes worse CSS formatting for our #}
+  {# generated common API index since we inline bare functions that become root-level rather than modules. #}
   {#<div class="doc doc-contents {% if root %}first{% endif %}">#}
-  <div class="doc doc-contents {% if root %}{% endif %}">
+  <div class="doc doc-contents">
     {% with docstring_sections = function.docstring.parsed %}
       {% include "docstring.html" with context %}
     {% endwith %}