Autogenerate documentation of the serialized data model (#521)

* Add autogen_serialized_datamodel script.
* Add unit test 
* Add the serialized schema docs to the manual.
* Add in docstrings and label versions.
* Add link to autogenerated file specification.
* Update path in Makefile.
* Also get properties for opentime classes.
* Remove old schema documentation
* Add second doc that doesn't have docstrings

- second doc isn't linked by the documentation, and only has lists of
  the fields

* Add copyright notice.

Makefile

@@ -99,6 +99,11 @@ ifndef FLAKE8_PROG
 endif
 	@python -m flake8
 
+doc-model:
+	@python opentimelineio/console/autogen_serialized_datamodel.py --dryrun
+
+doc-model-update:
+	@python opentimelineio/console/autogen_serialized_datamodel.py -o docs/tutorials/otio-serialized-schema.md
 
 # generate documentation in html
 doc-html:

docs/index.rst

@@ -41,6 +41,7 @@ Tutorials
    tutorials/contributing
    tutorials/feature-matrix
    tutorials/otio-file-format-specification
+   tutorials/otio-serialized-schema
    tutorials/otio-timeline-structure
    tutorials/time-ranges
    tutorials/write-an-adapter

docs/tutorials/otio-file-format-specification.md

@@ -215,64 +215,4 @@ TODO: Explain how metadata works and why we do it that way.
 
 ## Schema Specification
 
-Each OTIO data type (schema) defines its own key/value pairs. Here are the details of each.
-
-This list has the expanded fields of each concrete object type that you are likely to encounter in an OTIO file. It does not have the intermediate parent classes (Composition, Item, SerializableObject, etc.)
-
-### Timeline.1
-* name (string)
-* tracks (Stack)
-* global_start_time (RationalTime)
-* metadata (dict)
-
-### Sequence.1
-* name (string)
-* children (any Composable objects, like Clip, Transition, Filler, Stack, Sequence)
-* metadata (dict)
-* kind (string enumeration SequenceKind.Video, etc.)
-* source_range (TimeRange, may be null)
-* effects (list of Effect)
-* markers (list of Markers)
-
-### Stack.1
-* name (string)
-* children (any Composable objects, like Clip, Transition, Filler, Stack, Sequence)
-* metadata (dict)
-* source_range (TimeRange, may be null)
-* effects (list of Effect)
-* markers (list of Markers)
-
-### Clip.1
-* name (string)
-* metadata (dict)
-* source_range (TimeRange, may be null)
-* effects (list of Effect)
-* markers (list of Markers)
-* media_reference (MediaReference, may be null)
-
-### MediaReference.1
-* name (string)
-* available_range (TimeRange, may be null)
-* metadata (dict)
-
-### Filler.1
-* name (string)
-* metadata (dict)
-* source_range (TimeRange, may be null)
-* effects (list of Effect)
-* markers (list of Markers)
-
-### Transition.1
-* name (string)
-* metadata (dict)
-* transition_type (string)
-* in_offset (TimeRange)
-* out_offset (TimeRange)
-
-### RationalTime.1
-* value (double)
-* rate (double)
-
-### TimeRange.1
-* start_time (RationalTime)
-* duration (RationalTime)
+To see an autogenerated documentation of the serialized types and their fields, see this: <a href="otio-serialized-schema.md" target="_blank">Autogenerated Serialized File Format</a>

docs/tutorials/otio-serialized-schema-only-fields.md

@@ -0,0 +1,249 @@
+# OpenTimelineIO Serialized Data Documentation
+
+This document is a list of all the OpenTimelineIO classes that serialize to and
+from JSON, omitting plugins classes and docstrings.
+
+This document is automatically generated by running
+ docs/autogen_serialized_datamodel.py, or by running `make doc-model`.  It is
+ part of the unit tests suite and should be updated whenever the schema changes.
+ If it needs to be updated, run: `make doc-model-update` and this file should be
+ regenerated.
+
+# Classes
+
+
+## Module: opentimelineio.adapters
+
+### Adapter.1
+
+parameters:
+- *execution_scope*
+- *filepath*
+- *name*
+- *suffixes*
+
+## Module: opentimelineio.core
+
+### Composable.1
+
+parameters:
+- *metadata*
+- *name*
+
+### Composition.1
+
+parameters:
+- *children*
+- *effects*
+- *markers*
+- *metadata*
+- *name*
+- *source_range*
+
+### Item.1
+
+parameters:
+- *effects*
+- *markers*
+- *metadata*
+- *name*
+- *source_range*
+
+### MediaReference.1
+
+parameters:
+- *available_range*
+- *metadata*
+- *name*
+
+## Module: opentimelineio.hooks
+
+### HookScript.1
+
+parameters:
+- *execution_scope*
+- *filepath*
+- *name*
+
+## Module: opentimelineio.media_linker
+
+### MediaLinker.1
+
+parameters:
+- *execution_scope*
+- *filepath*
+- *name*
+
+## Module: opentimelineio.opentime
+
+### RationalTime.1
+
+parameters:
+- *rate*
+- *value*
+
+### TimeRange.1
+
+parameters:
+- *duration*
+- *start_time*
+
+### TimeTransform.1
+
+parameters:
+- *offset*
+- *rate*
+- *scale*
+
+## Module: opentimelineio.plugins
+
+### PluginManifest.1
+
+parameters:
+- *adapters*
+- *hook_scripts*
+- *hooks*
+- *media_linkers*
+- *schemadefs*
+
+### PythonPlugin.1
+
+parameters:
+- *execution_scope*
+- *filepath*
+- *name*
+
+## Module: opentimelineio.schema
+
+### Clip.1
+
+parameters:
+- *effects*
+- *markers*
+- *media_reference*
+- *metadata*
+- *name*
+- *source_range*
+
+### Effect.1
+
+parameters:
+- *effect_name*
+- *metadata*
+- *name*
+
+### FreezeFrame.1
+
+parameters:
+- *effect_name*
+- *metadata*
+- *name*
+- *time_scalar*
+
+### LinearTimeWarp.1
+
+parameters:
+- *effect_name*
+- *metadata*
+- *name*
+- *time_scalar*
+
+### TimeEffect.1
+
+parameters:
+- *effect_name*
+- *metadata*
+- *name*
+
+### ExternalReference.1
+
+parameters:
+- *available_range*
+- *metadata*
+- *name*
+- *target_url*
+
+### Gap.1
+
+parameters:
+- *effects*
+- *markers*
+- *metadata*
+- *name*
+- *source_range*
+
+### GeneratorReference.1
+
+parameters:
+- *available_range*
+- *generator_kind*
+- *metadata*
+- *name*
+- *parameters*
+
+### Marker.2
+
+parameters:
+- *color*
+- *marked_range*
+- *metadata*
+- *name*
+
+### MissingReference.1
+
+parameters:
+- *available_range*
+- *metadata*
+- *name*
+
+### SchemaDef.1
+
+parameters:
+- *execution_scope*
+- *filepath*
+- *name*
+
+### SerializableCollection.1
+
+parameters:
+- *children*
+- *metadata*
+- *name*
+
+### Stack.1
+
+parameters:
+- *children*
+- *effects*
+- *markers*
+- *metadata*
+- *name*
+- *source_range*
+
+### Timeline.1
+
+parameters:
+- *global_start_time*
+- *metadata*
+- *name*
+- *tracks*
+
+### Track.1
+
+parameters:
+- *children*
+- *effects*
+- *kind*
+- *markers*
+- *metadata*
+- *name*
+- *source_range*
+
+### Transition.1
+
+parameters:
+- *in_offset*
+- *metadata*
+- *name*
+- *out_offset*
+- *transition_type*