Fix python docstrings for dataframe APIs (rerun-io#7761)

### What
- Resolves: rerun-io#7760
- Confirms that every item in `rerun_bindings.pyi` has a docstring
- Validates that the docstrings from the .pyi actually match the
`__doc__` strings provided by pyo3
- Updates griffe / mkdocstrings to get them to do the right thing

TODO:
 - [x] Fix all the new issues this uncovers
- [x] Clean up some of the docstrings where necessary to include Param
defs, etc.
- [x] Either get griffe to handle the missing .so or move doc tests to
an environment with the built wheel

If anybody wants to tackle cleaning some of this up:
- Write docstrings on things in the `.pyi` file
- Add matching docstrings to the corresponding rust functions
- Run `pixi run py-build` and then `pixi run py-check-signatures` to
verify everything looks good

### Checklist
* [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)
* [x] I've included a screenshot or gif (if applicable)
* [x] I have tested the web demo (if applicable):
* Using examples from latest `main` build:
[rerun.io/viewer](https://rerun.io/viewer/pr/7761?manifest_url=https://app.rerun.io/version/main/examples_manifest.json)
* Using full set of examples from `nightly` build:
[rerun.io/viewer](https://rerun.io/viewer/pr/7761?manifest_url=https://app.rerun.io/version/nightly/examples_manifest.json)
* [x] The PR title and labels are set such as to maximize their
usefulness for the next release's CHANGELOG
* [x] If applicable, add a new check to the [release
checklist](https://github.com/rerun-io/rerun/blob/main/tests/python/release_checklist)!
* [x] If have noted any breaking changes to the log API in
`CHANGELOG.md` and the migration guide

- [PR Build Summary](https://build.rerun.io/pr/7761)
- [Recent benchmark results](https://build.rerun.io/graphs/crates.html)
- [Wasm size tracking](https://build.rerun.io/graphs/sizes.html)

To run all checks from `main`, comment on the PR with `@rerun-bot
full-check`.

.github/workflows/contrib_checks.yml

@@ -64,7 +64,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.8"
+          python-version: "3.9"
 
       - name: Install Python dependencies
         shell: bash

.github/workflows/reusable_checks_python.yml

@@ -56,7 +56,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.8"
+          python-version: "3.9"
           cache: "pip"
           cache-dependency-path: "rerun_py/requirements-doc.txt"
 

rerun_py/docs/css/mkdocstrings.css

@@ -61,3 +61,7 @@ code {
 .md-typeset a {
   --md-typeset-a-color: #526cfe;
 }
+
+.md-typeset h5 {
+  text-transform: revert;
+}

rerun_py/docs/gen_common_index.py

@@ -301,6 +301,29 @@ class Section:
     ),
     ################################################################################
     # Remaining sections
+    Section(
+        title="Dataframe",
+        mod_path="rerun.dataframe",
+        func_list=[
+            "load_archive",
+            "load_recording",
+        ],
+        class_list=[
+            "ComponentColumnDescriptor",
+            "ComponentColumnSelector",
+            "IndexColumnDescriptor",
+            "IndexColumnSelector",
+            "Recording",
+            "RecordingView",
+            "RRDArchive",
+            "Schema",
+            "AnyColumn",
+            "AnyComponentColumn",
+            "ComponentLike",
+            "ViewContentsLike",
+        ],
+        show_tables=True,
+    ),
     Section(
         title="Script Helpers",
         func_list=[
@@ -359,7 +382,8 @@ def is_mentioned(thing: str) -> bool:
 
 
 # Virtual folder where we will generate the md files
-root = Path(__file__).parent.parent.joinpath("rerun_sdk").resolve()
+rerun_py_root = Path(__file__).parent.parent.resolve()
+sdk_root = Path(__file__).parent.parent.joinpath("rerun_sdk").resolve()
 common_dir = Path("common")
 
 # Make sure all archetypes are included in the index:
@@ -370,8 +394,16 @@ def is_mentioned(thing: str) -> bool:
 # Lots of other potentially interesting stuff we could pull out in the future
 # This is what mkdocstrings uses under the hood
 search_paths = [path for path in sys.path if path]  # eliminate empty path
-search_paths.insert(0, root.as_posix())
-rerun_pkg = griffe.load("rerun", search_paths=search_paths)
+
+# This is where maturin puts rerun_bindings
+search_paths.insert(0, rerun_py_root.as_posix())
+# This is where the rerun package is
+search_paths.insert(0, sdk_root.as_posix())
+
+loader = griffe.GriffeLoader(search_paths=search_paths)
+
+bindings_pkg = loader.load("rerun_bindings", find_stubs_package=True)
+rerun_pkg = loader.load("rerun")
 
 # Create the nav for this section
 nav = mkdocs_gen_files.Nav()
@@ -438,6 +470,12 @@ def make_slug(s: str) -> str:
                     fd.write("      filters: []\n")
                 if section.show_submodules:
                     fd.write("      show_submodules: True\n")
+            # Helpful for debugging
+            if 0:
+                with mkdocs_gen_files.open(write_path, "r") as fd:
+                    print("FOR SECTION", section.title)
+                    print(fd.read())
+                    print()
 
         # Write out a table for the section in the index_file
         if section.show_tables:
@@ -446,6 +484,9 @@ def make_slug(s: str) -> str:
                 index_file.write("Function | Description\n")
                 index_file.write("-------- | -----------\n")
                 for func_name in section.func_list:
+                    if section.mod_path != "rerun":
+                        mod_tail = section.mod_path.split(".")[1:]
+                        func_name = ".".join(mod_tail + [func_name])
                     func = rerun_pkg[func_name]
                     index_file.write(f"[`rerun.{func_name}()`][rerun.{func_name}] | {func.docstring.lines[0]}\n")
             if section.class_list:

rerun_py/mkdocs.yml

@@ -19,10 +19,10 @@ theme:
 plugins:
   - search # https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/
   - mkdocstrings: # https://mkdocstrings.github.io/usage/#global-options
-      custom_templates: rerun_py/docs/templates # Override the function template. NOTE: relative to working directory. (https://github.com/mkdocstrings/mkdocstrings/issues/477)
+      custom_templates: docs/templates # Override the function template.
       handlers:
         python:
-          paths: ["rerun_sdk"] # Lookup python modules relative to this path
+          paths: ["rerun_sdk", "."] # Lookup python modules relative to this path
           import: # Cross-references for python and numpy
             - https://arrow.apache.org/docs/objects.inv
             - https://docs.python.org/3/objects.inv
@@ -44,6 +44,12 @@ plugins:
             merge_init_into_class: false # Not compatible with `inherited_members`
             show_if_no_docstring: false # We intentionally hide archetype fields
             show_source: no
+            load_external_modules: true
+            preload_modules:
+              - rerun_bindings
+            annotations_path: brief
+            signature_crossrefs: true
+
   - gen-files: # https://oprypin.github.io/mkdocs-gen-files
       scripts:
         - docs/gen_common_index.py

rerun_py/requirements-doc.txt

@@ -1,12 +1,12 @@
-griffe==0.39.0
-mkdocs==1.5.3
+griffe==1.4.1
+mkdocs==1.6.1
 mkdocs-gen-files==0.5.0
 mkdocs-literate-nav==0.6.1
 mkdocs-material==9.4.7
 mkdocs-material-extensions==1.3
 git+https://github.com/rerun-io/[email protected] # forked mkdocs-redirects with https://github.com/rerun-io/mkdocs-redirects/commit/d367a0847928438b66f73508e49852be1190409b
-mkdocstrings==0.23.0
-mkdocstrings-python==1.7.3
+mkdocstrings==0.26.2
+mkdocstrings-python==1.12.1
 mike==1.1.2
 sphobjinv==2.3.1
 typing_extensions==4.8.0 # uncaptured dep for mkdocstrings (https://github.com/mkdocstrings/mkdocstrings/issues/548)