Skip to content

Add missing docstrings for Item/MediaReference, fix RationalTime math formatting - #2051

Open
hikmetba-bit wants to merge 2 commits into
AcademySoftwareFoundation:mainfrom
hikmetba-bit:docs/item-mediareference-rationaltime-docstrings
Open

hikmetba-bit wants to merge 2 commits into
AcademySoftwareFoundation:mainfrom
hikmetba-bit:docs/item-mediareference-rationaltime-docstrings

Conversation

@hikmetba-bit

Copy link
Copy Markdown

Summary

Fixes #2042 (partially — targets the three concrete examples named in the issue: Item, MediaReference, RationalTime).

  • Item and MediaReference had no class-level docstring in their pybind bindings (py::class_<Item, ...>(m, "Item", py::dynamic_attr()) with no doc argument), so https://opentimelineio.readthedocs.io/en/stable/tutorials/otio-serialized-schema.html#item-1 and #mediareference-1 showed None. Added docstrings following the existing style used by sibling classes (Composition, Clip), cross-referencing their concrete subclasses.
  • RationalTime's docstring used a Sphinx :math: role referencing an undefined rt variable (:math:\rt.value/rt.rate`). This role is never actually rendered as math — the same docstring is also dumped verbatim into a plain code fence by autogen_serialized_datamodel.py` for the schema doc page — so it just showed up as confusing literal text. Replaced it with plain double-backtick formatting and expanded the description slightly, matching the issue's "too short" note.

docs/tutorials/otio-serialized-schema.md is regenerated by hand to match, since test_serialized_schema.py asserts the checked-in file matches what autogen_serialized_datamodel.py produces from the live docstrings.

Test plan

  • Could not build the C++ extension in this environment (no CMake/MSVC toolchain available), so test_serialized_schema.py was not run directly.
  • Manually reproduced the generator's exact text-processing (inspect.cleandoc + the textwrap.wrap(width=100, replace_whitespace=False, drop_whitespace=False, break_long_words=False) pass from autogen_serialized_datamodel.py) against the new docstrings in a plain Python script to confirm the wrapped output matches byte-for-byte what was written into otio-serialized-schema.md.
  • Cross-checked that every attribute/class referenced in the new docstrings (source_range, available_range, available_image_bounds, value, rate, ExternalReference, GeneratorReference, ImageSequenceReference, MissingReference) actually exists as a bound property/class in the same bindings files.
  • Did not touch otio-serialized-schema-only-fields.md, since that file omits docstrings entirely and is unaffected.

🤖 Generated with Claude Code

…math formatting

Item and MediaReference had no class-level docstring in their pybind
bindings, so the generated schema docs (otio-serialized-schema.md)
showed "None" for both. Added docstrings following the same style as
sibling classes (Composition, Clip).

RationalTime's docstring used a Sphinx `:math:` role referencing an
undefined `rt` variable, which is never rendered as math (the doc is
also dumped verbatim into a plain code fence by
autogen_serialized_datamodel.py) and just showed up as literal,
confusing text. Replaced it with plain formatting and expanded the
description slightly per the issue's request.

Regenerated docs/tutorials/otio-serialized-schema.md by hand to match,
since test_serialized_schema.py compares the checked-in file against
the docstrings.

Fixes AcademySoftwareFoundation#2042

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@linux-foundation-easycla

linux-foundation-easycla Bot commented Sep 16, 2026

Copy link
Copy Markdown

CLA Not Signed

@codecov-commenter

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 0% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.48%. Comparing base (a639246) to head (a2eecf9).

Files with missing lines Patch % Lines
...entimelineio-bindings/otio_serializableObjects.cpp 0.00% 2 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@           Coverage Diff           @@
##             main    #2051   +/-   ##
=======================================
  Coverage   83.48%   83.48%           
=======================================
  Files         182      182           
  Lines       13517    13517           
  Branches     1254     1254           
=======================================
  Hits        11284    11284           
  Misses       2060     2060           
  Partials      173      173           
Flag Coverage Δ
py-unittests 83.48% <0.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
...lineio/opentime-bindings/opentime_rationalTime.cpp 87.03% <ø> (ø)
...entimelineio-bindings/otio_serializableObjects.cpp 84.46% <0.00%> (ø)

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a639246...a2eecf9. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Extends the previous commit's class-level docstrings with the
per-property descriptions for Item (source_range, color, markers,
effects, available_image_bounds), MediaReference (available_range,
available_image_bounds, is_missing_reference), and
RationalTime (value, rate), and updates the corresponding entries in
docs/tutorials/otio-serialized-schema.md.

Left SerializableObjectWithMetadata.name/metadata undocumented here:
since they're inherited by nearly every schema class, documenting
them would touch ~40 unrelated bullet points across the generated
schema doc, which is safer to do via an actual `make doc-model-update`
run than by hand.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Some documentation is missing

3 participants