Autogenerate documentation of the serialized data model

[ssteinbach]

Adds a script that autogenerates a markdown file containing the serialized classes and their serialized properties only. Also adds a unit test that checks to see if that document needs to be updated.

TODO:

• Add schema version numbers to document
• Add a reference from the file format schema doc to this doc
• Add documentation to the unit test on how to update the doc using the make target
• Makefile target is out of date and needs to point at the correct path
• Add opentime classes as well
• Remove existing notes on schema
• Add second file, without documentation, just the fields to the docs folder.

Resulting page can be viewed here: https://github.com/ssteinbach/OpenTimelineIO/blob/document_serialized_data_model/docs/tutorials/otio-serialized-schema.md

Schema only page (no documentation):
https://github.com/ssteinbach/OpenTimelineIO/blob/document_serialized_data_model/docs/tutorials/otio-serialized-schema-only-fields.md

[codecov-io]

Codecov Report

Merging #521 into master will decrease coverage by 0.13%.
The diff coverage is 78.64%.

@@            Coverage Diff             @@
##           master     #521      +/-   ##
==========================================
- Coverage   88.82%   88.68%   -0.14%     
==========================================
  Files          68       69       +1     
  Lines        7394     7497     +103     
==========================================
+ Hits         6568     6649      +81     
- Misses        826      848      +22

Impacted Files	Coverage Δ
opentimelineio/console/__init__.py	100% <ø> (ø)	⬆️
...timelineio/console/autogen_serialized_datamodel.py	78.64% <78.64%> (ø)

---

Continue to review full report at Codecov.

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

[reinecke]

I really like the idea of this! It keeps documentation up to date with schema changes, allows looking for schema changes based on git history of the documentation, and forces schema changes to be spotlit in PRs.

One thought that occurs to me is that it may be nice to add a more terse version of this schema document that doesn't include docstrings. If looking at the git history of this schema dump to find material schema changes docstring refinement and updates will, more often than not, be cosmetic in that context. By having a dump without docstrings available there will be a file where all changes in git history are material changes to the schema.

[ssteinbach]

@reinecke interesting suggestion. Where would you put a document like that? (just the schema, no docstrings).

[reinecke]

Knee-jerk, tests/sample_data feels like the current best fit. I don't have too strong of opinions however.

Also this suggestion may live a bit in the uncanny valley between documenting the data model and having a more formal spec, so I'd understand if it felt out-of-scope for this PR.

[jminor]

I think this is a good idea as long as it is clearly labelled as auto-generated. This can be a good evolutionary step towards the formal spec.

[ssteinbach]

tests/sample_data doesn't feel correct. I feel like it should go somewhere in the documentation area if anywhere. Do you think the unit test should cover the version w/ documentation? or just the bare one that you're proposing?

[jminor]

I think the output should go into docs/ and it should include the doc strings.

[ssteinbach]

@reinecke @jminor just to clarify:

1. In addition to the version of this document with docstrings, there should be a second version without docstrings so that just changes to the serialized format are visible.
2. The file with docstrings goes into docs/tutorials currently. The file without docstrings would go into docs
3. The file without docstrings would not get referenced by the documentation pages, which instead reference the file with docstrings
4. The existing schema notes in: https://opentimelineio.readthedocs.io/en/latest/tutorials/otio-file-format-specification.html would get removed (replaced by the auto-generated, up to date version this PR makes)
5. The unit test is currently running against the version with docstrings... for keeping the documentation up to date that is probably nice, but if all we care about is correctness, then we might want to run it against the version without docstrings

[ssteinbach]

Alright, I created a second file, that isn't linked by the docs but is in that directory. The unit test runs against the exhaustive one (with docstrings) to ensure that document is always up to date.

[reinecke]

Overall, that seems to hit the mark.
Ultimately we're talking about two docs with specific purposes here:

• version without docstrings: meant to trigger a test failure when there are schema updates and highlight PRs that may affect the schema.
• version with docstrings: provides helpful documentation for humans and should be kept up to date with the current state of affairs.

So it seems that test failures looking for diffs in these have separate goals:

• The without docstrings test failure indicates that the change may be potentially breaking to existing serialized files
• The with docstring test failure indicates that the change has left the documentation out of sync with the current code

All this is a long way of saying, would it make sense to have the with docstring version auto-generated as part of the documentation publishing rather than checking it into the repo? Then the without one is checked into the repo and triggers test failure when out of sync.