From a9ad60e558b7b12bf8f5e30b6d7d2c5a3bdf1895 Mon Sep 17 00:00:00 2001 From: Jeremy Leibs Date: Tue, 15 Oct 2024 23:23:11 -0400 Subject: [PATCH] Fix mkdocs to work with docs coming from rerun_bindings --- rerun_py/docs/css/mkdocstrings.css | 4 ++++ rerun_py/docs/gen_common_index.py | 31 ++++++++++++++++++++++++++- rerun_py/mkdocs.yml | 7 ++++-- rerun_py/requirements-doc.txt | 8 +++---- rerun_py/rerun_sdk/rerun/dataframe.py | 1 + 5 files changed, 44 insertions(+), 7 deletions(-) diff --git a/rerun_py/docs/css/mkdocstrings.css b/rerun_py/docs/css/mkdocstrings.css index 33f390c1d8697..7c24f829e1f6c 100644 --- a/rerun_py/docs/css/mkdocstrings.css +++ b/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; +} diff --git a/rerun_py/docs/gen_common_index.py b/rerun_py/docs/gen_common_index.py index 1479730878352..2777d9cee2db6 100755 --- a/rerun_py/docs/gen_common_index.py +++ b/rerun_py/docs/gen_common_index.py @@ -301,6 +301,25 @@ 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", + ], + show_tables=True, + ), Section( title="Script Helpers", func_list=[ @@ -360,6 +379,7 @@ def is_mentioned(thing: str) -> bool: # Virtual folder where we will generate the md files root = Path(__file__).parent.parent.joinpath("rerun_sdk").resolve() +bindings = Path(__file__).parent.parent.joinpath("rerun_bindings").resolve() common_dir = Path("common") # Make sure all archetypes are included in the index: @@ -370,8 +390,14 @@ 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, bindings.as_posix()) search_paths.insert(0, root.as_posix()) -rerun_pkg = griffe.load("rerun", search_paths=search_paths) + +loader = griffe.GriffeLoader(search_paths=search_paths, allow_inspection=True) + +bindings_pkg = loader.load("rerun_bindings") +rerun_pkg = loader.load("rerun") # Create the nav for this section nav = mkdocs_gen_files.Nav() @@ -446,6 +472,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: diff --git a/rerun_py/mkdocs.yml b/rerun_py/mkdocs.yml index 4030de2ce4d01..fcbe7f4d00d13 100644 --- a/rerun_py/mkdocs.yml +++ b/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", "rerun_bindings"] # 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,9 @@ 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 - gen-files: # https://oprypin.github.io/mkdocs-gen-files scripts: - docs/gen_common_index.py diff --git a/rerun_py/requirements-doc.txt b/rerun_py/requirements-doc.txt index 5b1377c0024c5..5c30f70bb9381 100644 --- a/rerun_py/requirements-doc.txt +++ b/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/mkdocs-redirects.git@v1.3.1 # 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) diff --git a/rerun_py/rerun_sdk/rerun/dataframe.py b/rerun_py/rerun_sdk/rerun/dataframe.py index 56a466682d1a5..27a5305f74565 100644 --- a/rerun_py/rerun_sdk/rerun/dataframe.py +++ b/rerun_py/rerun_sdk/rerun/dataframe.py @@ -6,6 +6,7 @@ IndexColumnDescriptor as IndexColumnDescriptor, IndexColumnSelector as IndexColumnSelector, Recording as Recording, + RecordingView as RecordingView, RRDArchive as RRDArchive, Schema as Schema, load_archive as load_archive,