Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix python docstrings for dataframe APIs #7761

Merged
merged 12 commits into from
Oct 17, 2024
Prev Previous commit
Next Next commit
Fix mkdocs to work with docs coming from rerun_bindings
jleibs committed Oct 16, 2024
commit 620ec74a488a2ca396fd921a3f7299b839060787
4 changes: 4 additions & 0 deletions rerun_py/docs/css/mkdocstrings.css
Original file line number Diff line number Diff line change
@@ -61,3 +61,7 @@ code {
.md-typeset a {
--md-typeset-a-color: #526cfe;
}

.md-typeset h5 {
text-transform: revert;
}
31 changes: 30 additions & 1 deletion rerun_py/docs/gen_common_index.py
Original file line number Diff line number Diff line change
@@ -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:
7 changes: 5 additions & 2 deletions rerun_py/mkdocs.yml
Original file line number Diff line number Diff line change
@@ -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
8 changes: 4 additions & 4 deletions rerun_py/requirements-doc.txt
Original file line number Diff line number Diff line change
@@ -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)
1 change: 1 addition & 0 deletions rerun_py/rerun_sdk/rerun/dataframe.py
Original file line number Diff line number Diff line change
@@ -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,