Update all of the docstrings on public-facing APIs to numpy style (#1001

)

* Update __init__.py

* More docstrings

* lints

* Tweak the material class template

* Add some extra spacing

* Docstrings for the dataclasses

* Update obb docstring

* docstrings for camera

* docstrings for meshes and images

* More docstring linting

* docstrings for lines

* Docstrings for images

* docstrings for points

* docstrings for rects

* Docstrings for scalar

* Docstrings for tensor

* Docstrings for text

* docstrings for transforms

* Make tabs sticky

* Revert usage of type subscriptions since not in python 3.8

* unused import

* Fix docstring for rerun.init()

* Consistency in points doc

rerun_py/docs/common/SUMMARY.txt

@@ -2,5 +2,6 @@
 * [Initialization](initialization.md)
 * [Logging Primitives](primitives.md)
 * [Logging Images](images.md)
+* [Annotations](annotation.md)
 * [Plotting](plotting.md)
 * [Transforms](transforms.md)

rerun_py/docs/common/annotation.md

@@ -0,0 +1 @@
+::: rerun.log_annotation_context

rerun_py/docs/common/images.md

@@ -2,4 +2,3 @@
 ::: rerun.log_image_file
 ::: rerun.log_depth_image
 ::: rerun.log_segmentation_image
-::: rerun.log_annotation_context

rerun_py/docs/css/mkdocstrings.css

@@ -8,3 +8,8 @@ div.doc-contents:not(.first) {
 td code {
   word-break: normal !important;
 }
+
+/* Add extra spacing between doc-objects. */
+div.doc-object {
+  margin-bottom: 2rem;
+}

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

@@ -0,0 +1,123 @@
+{# Very minimally patched from:
+https://github.com/mkdocstrings/python/blob/master/src/mkdocstrings_handlers/python/templates/material/_base/class.html
+
+See: CHANGE comments below
+#}
+
+{{ log.debug("Rendering " + class.path) }}
+
+<div class="doc doc-object doc-class">
+{% with html_id = class.path %}
+
+  {% if root %}
+    {% set show_full_path = config.show_root_full_path %}
+    {% set root_members = True %}
+  {% elif root_members %}
+    {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+    {% set root_members = False %}
+  {% else %}
+    {% set show_full_path = config.show_object_full_path %}
+  {% endif %}
+
+  {% if not root or config.show_root_heading %}
+
+    {% filter heading(heading_level,
+        role="class",
+        id=html_id,
+        class="doc doc-heading",
+        toc_label=class.name) %}
+
+      {% if config.separate_signature %}
+        <span class="doc doc-object-name doc-class-name">{% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}</span>
+      {% elif config.merge_init_into_class and "__init__" in class.members -%}
+        {%- with function = class.members["__init__"] -%}
+          {%- filter highlight(language="python", inline=True) -%}
+            {# CHANGE: Insert class before class for better highlighting #}
+            class {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
+            {%- include "signature.html" with context -%}
+          {%- endfilter -%}
+        {%- endwith -%}
+      {% else %}
+        {# CHANGE: Insert class before class for better highlighting #}
+          {%- filter highlight(language="python", inline=True) -%}
+            class {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
+          {%- endfilter -%}
+      {% endif %}
+
+      {% with labels = class.labels %}
+        {% include "labels.html" with context %}
+      {% endwith %}
+
+    {% endfilter %}
+
+    {% if config.separate_signature and config.merge_init_into_class %}
+      {% if "__init__" in class.members %}
+        {% with function = class.members["__init__"] %}
+          {% filter highlight(language="python", inline=False) %}
+            {% filter format_signature(config.line_length) %}
+              {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
+              {% include "signature.html" with context %}
+            {% endfilter %}
+          {% endfilter %}
+        {% endwith %}
+      {% endif %}
+    {% endif %}
+
+  {% else %}
+    {% if config.show_root_toc_entry %}
+      {% filter heading(heading_level,
+          role="class",
+          id=html_id,
+          toc_label=class.path if config.show_root_full_path else class.name,
+          hidden=True) %}
+      {% endfilter %}
+    {% endif %}
+    {% set heading_level = heading_level - 1 %}
+  {% endif %}
+
+  <div class="doc doc-contents {% if root %}first{% endif %}">
+    {% if config.show_bases and class.bases %}
+      <p class="doc doc-class-bases">
+        Bases: {% for expression in class.bases -%}
+          <code>{% include "expression.html" with context %}</code>{% if not loop.last %}, {% endif %}
+        {% endfor -%}
+      </p>
+    {% endif %}
+
+    {% with docstring_sections = class.docstring.parsed %}
+      {% include "docstring.html" with context %}
+    {% endwith %}
+
+    {% if config.merge_init_into_class %}
+      {% if "__init__" in class.members and class.members["__init__"].has_docstring %}
+        {% with docstring_sections = class.members["__init__"].docstring.parsed %}
+          {% include "docstring.html" with context %}
+        {% endwith %}
+      {% endif %}
+    {% endif %}
+
+    {% if config.show_source %}
+      {% if config.merge_init_into_class %}
+        {% if "__init__" in class.members and class.members["__init__"].source %}
+          <details class="quote">
+            <summary>Source code in <code>{{ class.relative_filepath }}</code></summary>
+            {{ class.members["__init__"].source|highlight(language="python", linestart=class.members["__init__"].lineno, linenums=True) }}
+          </details>
+        {% endif %}
+      {% elif class.source %}
+        <details class="quote">
+          <summary>Source code in <code>{{ class.relative_filepath }}</code></summary>
+          {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }}
+        </details>
+      {% endif %}
+    {% endif %}
+
+    {% with obj = class %}
+      {% set root = False %}
+      {% set heading_level = heading_level + 1 %}
+      {% include "children.html" with context %}
+    {% endwith %}
+  </div>
+
+{% endwith %}
+</div>

rerun_py/mkdocs.yml

@@ -9,11 +9,12 @@ repo_url: https://github.com/rerun-io/rerun/
 theme:
   name: "material"
   features:
-    - navigation.tabs
-    - navigation.instant
+    - navigation.expand
     - navigation.indexes
+    - navigation.instant
+    - navigation.tabs
+    - navigation.tabs.sticky
     - navigation.tracking
-    - navigation.expand
 
 plugins:
   - search # https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/
@@ -31,6 +32,7 @@ plugins:
             members_order: source
             heading_level: 3
             show_root_heading: true
+            merge_init_into_class: true
   - gen-files: # https://oprypin.github.io/mkdocs-gen-files
       scripts:
         - docs/gen_package_index.py

rerun_py/rerun/__init__.py

@@ -74,6 +74,12 @@ def get_recording_id() -> str:
     processes to log to the same Rerun instance (and be part of the same recording),
     you will need to manually assign them all the same recording_id.
     Any random UUIDv4 will work, or copy the recording id for the parent process.
+
+    Returns
+    -------
+    str
+        The recording ID that this process is logging to.
+
     """
     return str(bindings.get_recording_id())
 
@@ -90,6 +96,12 @@ def set_recording_id(value: str) -> None:
     processes to log to the same Rerun instance (and be part of the same recording),
     you will need to manually assign them all the same recording_id.
     Any random UUIDv4 will work, or copy the recording id for the parent process.
+
+    Parameters
+    ----------
+    value : str
+        The recording ID to use for this process.
+
     """
     bindings.set_recording_id(value)
 
@@ -107,7 +119,6 @@ def init(application_id: str, spawn_and_connect: bool = False) -> None:
         For instance, if you have one application doing object detection
         and another doing camera calibration, you could have
         `rerun.init("object_detector")` and `rerun.init("calibrator")`.
-
     spawn_and_connect : bool
         Spawn a Rerun Viewer and stream logging data to it.
         Short for calling `spawn_and_connect` separately.
@@ -143,7 +154,15 @@ def spawn_and_connect(port: int = 9876) -> None:
     This is often the easiest and best way to use Rerun.
     Just call this once at the start of your program.
 
-    See also: rerun.connect
+    Parameters
+    ----------
+    port : int
+        The port to connect to
+
+    See Also
+    --------
+     * [rerun.connect][]
+
     """
     spawn_viewer(port)
     connect(f"127.0.0.1:{port}")
@@ -157,12 +176,26 @@ def connect(addr: Optional[str] = None) -> None:
     Connect to a remote Rerun Viewer on the given ip:port.
 
     Requires that you first start a Rerun Viewer, e.g. with 'python -m rerun'
+
+    Parameters
+    ----------
+    addr : str
+        The ip:port to connect to
+
     """
     bindings.connect(addr)
 
 
 def spawn_viewer(port: int = 9876) -> None:
-    """Spawn a Rerun Viewer, listening on the given port."""
+    """
+    Spawn a Rerun Viewer, listening on the given port.
+
+    Parameters
+    ----------
+    port : int
+        The port to listen on.
+
+    """
     import subprocess
     import sys
     from time import sleep
@@ -205,6 +238,7 @@ def show() -> None:
     This will clear the logged data after showing it.
 
     NOTE: There is a bug which causes this function to only work once on some platforms.
+
     """
     bindings.show()
 
@@ -216,13 +250,19 @@ def save(path: str) -> None:
     This only works if you have not called `connect`.
 
     This will clear the logged data after saving.
+
+    Parameters
+    ----------
+    path : str
+        The path to save the data to.
+
     """
     bindings.save(path)
 
 
 def set_time_sequence(timeline: str, sequence: Optional[int]) -> None:
     """
-    Set the current time for this thread.
+    Set the current time for this thread as an integer sequence.
 
     Used for all subsequent logging on the same thread,
     until the next call to `set_time_sequence`.
@@ -232,13 +272,21 @@ def set_time_sequence(timeline: str, sequence: Optional[int]) -> None:
     You can remove a timeline again using `set_time_sequence("frame_nr", None)`.
 
     There is no requirement of monoticity. You can move the time backwards if you like.
+
+    Parameters
+    ----------
+    timeline : str
+        The name of the timeline to set the time for.
+    sequence : int
+        The current time on the timeline in integer units.
+
     """
     bindings.set_time_sequence(timeline, sequence)
 
 
 def set_time_seconds(timeline: str, seconds: Optional[float]) -> None:
     """
-    Set the current time for this thread.
+    Set the current time for this thread in seconds.
 
     Used for all subsequent logging on the same thread,
     until the next call to `set_time_seconds`.
@@ -254,6 +302,14 @@ def set_time_seconds(timeline: str, seconds: Optional[float]) -> None:
     since unix epoch.
 
     There is no requirement of monoticity. You can move the time backwards if you like.
+
+    Parameters
+    ----------
+    timeline : str
+        The name of the timeline to set the time for.
+    seconds : float
+        The current time on the timeline in seconds.
+
     """
     bindings.set_time_seconds(timeline, seconds)
 
@@ -276,5 +332,13 @@ def set_time_nanos(timeline: str, nanos: Optional[int]) -> None:
     unix epoch.
 
     There is no requirement of monoticity. You can move the time backwards if you like.
+
+    Parameters
+    ----------
+    timeline : str
+        The name of the timeline to set the time for.
+    nanos : int
+        The current time on the timeline in nanoseconds.
+
     """
     bindings.set_time_nanos(timeline, nanos)