Add missing docstrings for Item/MediaReference, fix RationalTime math formatting - #2051
Open
hikmetba-bit wants to merge 2 commits into
Conversation
…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>
|
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ 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
Flags with carried forward coverage won't be shown. Click here to find out more.
Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #2042 (partially — targets the three concrete examples named in the issue: Item, MediaReference, RationalTime).
ItemandMediaReferencehad 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-1showedNone. 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 undefinedrtvariable (: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 byautogen_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.mdis regenerated by hand to match, sincetest_serialized_schema.pyasserts the checked-in file matches whatautogen_serialized_datamodel.pyproduces from the live docstrings.Test plan
test_serialized_schema.pywas not run directly.inspect.cleandoc+ thetextwrap.wrap(width=100, replace_whitespace=False, drop_whitespace=False, break_long_words=False)pass fromautogen_serialized_datamodel.py) against the new docstrings in a plain Python script to confirm the wrapped output matches byte-for-byte what was written intootio-serialized-schema.md.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.otio-serialized-schema-only-fields.md, since that file omits docstrings entirely and is unaffected.🤖 Generated with Claude Code