Repository navigation
Conversation
|
Hey @jhodges10, can you please rebase the branch, there were some CI issues we have resolved now. |
Sure thing! |
|
I can see a ton of value in adapting this into a validation check. It could drive automation that could discover or bring attention to drift between the spec and the implementation. My feeling though is that the spec itself should be hand authored for clarity & to ensure intentionality. (Intentionality meaning, something in the spec is meant to be there, as opposed to propagated up from an implementation detail.) |
This adds a generator that assembles the OpenTimelineIO Core Specification from two sources: the code (every serializable schema object, its fields, field types, default values, inheritance, and binding docstrings) and a curated markdown overlay holding the human-authored narrative and per-object integrator usage guidance. Changes: - Enrich autogen_serialized_datamodel.py so the serialized-schema docs now carry per-field type info (derived from pybind11 getter signatures, normalized to spec vocabulary), optional flags, default values, and a class-level inheritance chain. Addresses the long-standing "type information would be awesome" TODO. - Add autogen_core_specification.py, which reuses that model and interleaves it with docs/spec/core-specification-overlay.md to produce a full specification document (docs/spec/otio-core-specification.md). The overlay is plain markdown with HTML-comment directives, parsed with the stdlib (no new dependencies). Generation fails unless every non-plugin schema object is documented exactly once, so the spec cannot silently drift from the code. - Fill in the missing per-field semantic docstrings on the bindings (otio and opentime) so the pure definitions live in code and flow into both the serialized-schema docs and the specification. - Wire up `make spec` / `make spec-update` and a regenerate-and-compare unit test (CoreSpecificationTester), matching the existing autogen doc pattern. Signed-off-by: Jeff Hodges <jeff@jeffhq.com>
e9a11de to
a6f63cc
Compare
@meshula I agree with you here in principle, but it would probably be nice to have some tooling that make that a little simpler. What about writing the spec using JSON Schema and leveraging some of the tooling around that? |
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #2024 +/- ##
==========================================
+ Coverage 83.62% 83.63% +0.01%
==========================================
Files 184 185 +1
Lines 13627 13924 +297
Branches 1270 1332 +62
==========================================
+ Hits 11395 11646 +251
- Misses 2059 2092 +33
- Partials 173 186 +13
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:
|
Signed-off-by: Jeff Hodges <jeff.hodges@hodgesbadge.com>
Signed-off-by: Jeff Hodges <jeff@jeffhq.com>
Signed-off-by: Jeff Hodges <jeff@jeffhq.com>
e1c0a4e to
96fc21c
Compare
Summary
This is a first step toward generating the OTIO Core Specification from the code rather than maintaining it by hand. It adds a generator that assembles a full specification document from two sources:
metadatadictionary, root objects, JSON serialization) and the per-object integrator usage guidance that doesn't belong in terse API docstrings.The per-object semantic definitions live in the binding docstrings (single source of truth, also improves IDE/readthedocs help); the narrative and usage guidance live in the overlay. The generator interleaves them.
What's here
autogen_serialized_datamodel.pyso the serialized-schema docs now carry per-field type info (derived from the pybind11 getter signatures, normalized to spec vocabulary —String,Double,Array[Effect],Map[String, MediaReference],TimeRange, …), optional flags, default values, and a class-level inheritance chain. (Resolves the long-standing# @TODO: having type information here would be awesome.)autogen_core_specification.py, which reuses that model and stitches it together with a curated overlay to producedocs/spec/otio-core-specification.md. The overlay (docs/spec/core-specification-overlay.md) is plain markdown with HTML-comment directives (@preamble/@section/@object/@appendix), parsed with the stdlib — no new dependencies.@objectentry. Adding a new schema to the code forces a matching overlay entry, so the spec can't silently drift.source_range,kind,global_start_time,available_range,target_url,RationalTime.value/rate,TimeRange.start_time/duration,name/metadata). These flow into both the serialized-schema docs and the specification.make spec/make spec-update, plus a regenerate-and-compare unit test (CoreSpecificationTester) matching the existing autogen-doc pattern.Regenerating
Edit prose in
docs/spec/core-specification-overlay.md; edit field/object definitions in the bindings.Testing
CoreSpecificationTester,SerializedSchemaTester, andPluginDocumentationTesterpass.Notes
0..1/0..*), per-property "inherited from" grouping, intra-document cross-links between object headings, and UML/diagrams.