Add cmake/C++ support to ReadTheDocs documentation generation. (#547)

* Use v2 RTD configuration.
* Add schema section to docs
* Update link in time-scopes
* Clean up docstrings to avoid warnings in sphinx
* Mark code blocks as such in core
* RTD config file should do the submodule sync
* Remove out of date proposal for C++ core

.readthedocs.yml

@@ -1,6 +1,20 @@
+# required by RTD
+version: 2
+
 build:
     image: latest
 
 python:
     version: 3.6
-    setup_py_install: true
+    install:
+      - method: pip
+        path: .
+        extra_requirements:
+          - cmake
+
+submodules:
+  include: all
+  recursive: true
+
+conda:
+  environment: readthedocs-conda.yml

MANIFEST.in

@@ -7,6 +7,7 @@ prune docs
 exclude .gitmodules
 recursive-exclude src *.git
 exclude .readthedocs.yml
+exclude readthedocs-conda.yml
 exclude .codecov.yml
 exclude .gitlab-ci.yml
 exclude .travis.yml

docs/conf.py

@@ -5,7 +5,7 @@
 
 PACKAGE_TITLE = 'OpenTimelineIO'
 PACKAGE_NAME = 'opentimelineio'
-PACKAGE_DIR = 'opentimelineio'
+PACKAGE_DIR = 'src/py-opentimelineio/opentimelineio'
 AUTHOR_NAME = 'Pixar Animation Studios'
 
 try:
@@ -282,8 +282,8 @@ def run_apidoc(_):
         '--module-first',
         '--output-dir',
         './api/modules',
-        '../opentimelineio'
-     ] + ignore_paths
+        '../src/py-opentimelineio/opentimelineio',
+    ] + ignore_paths
 
     from sphinx.ext import apidoc
     apidoc.main(argv)

docs/index.rst

@@ -40,16 +40,13 @@ Tutorials
    tutorials/architecture
    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
    tutorials/write-a-media-linker
    tutorials/write-a-hookscript
    tutorials/write-a-schemadef
    tutorials/versioning-schemas
-   tutorials/wrapping-otio
 
 Use Cases
 ------------
@@ -68,6 +65,16 @@ API Reference
 
    api/modules/opentimelineio
 
+Schema Reference
+----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorials/otio-file-format-specification
+   tutorials/otio-serialized-schema
+   tutorials/otio-serialized-schema-only-fields
+
 Indices and tables
 ------------------
 

docs/tutorials/time-ranges.md

@@ -10,7 +10,7 @@ nesting, cross-dissolves, trimming, and speed-up/slow-down effects which can
 lead to confusion. In an attempt to make this easy to work with OpenTimelineIO 
 uses the following terminology and API for dealing with time ranges.
 
-Note: You probably also want to refer to [Timeline Structure](otio-timeline-structure.html).
+Note: You probably also want to refer to [Timeline Structure](otio-timeline-structure.md).
 
 ## Clips
 

readthedocs-conda.yml

@@ -0,0 +1,5 @@
+# YAML file for configurating the Conda environment in read the docs.
+name: opentimelineio-readthedocs
+
+dependencies:
+  - cmake

setup.py

@@ -406,9 +406,11 @@ def test_otio():
         'opentimelineview': 'src/opentimelineview',
     },
 
-    install_requires=[
-        'pyaaf2==1.2.0',
-    ],
+    install_requires=(
+        [
+            'pyaaf2==1.2.0',
+        ]
+    ),
     entry_points={
         'console_scripts': [
             'otioview = opentimelineview.console:main',

src/py-opentimelineio/opentimelineio/adapters/fcp_xml.py

@@ -137,7 +137,7 @@ def context_pushing_element(self, element):
         :param element: Element to push to the stack.
         :return: The new context with the provided element pushed to the top
             of the stack.
-        :raises: :class:`ValueError` if the element is already in the stack.
+        :raises: :class: `ValueError` if the element is already in the stack.
         """
         for context_element in self.elements:
             if context_element == element:
@@ -215,7 +215,7 @@ def _rate_from_context(context):
     """
     Given the context object, gets the appropriate rate.
 
-    :param context: The :class:`_Context` instance to find the rate in.
+    :param context: The :class: `_Context` instance to find the rate in.
 
     :return: The rate value or ``None`` if no rate is available in the context.
     """
@@ -236,7 +236,7 @@ def _time_from_timecode_element(tc_element, context=None):
     :param tc_element: The ``timecode`` element.
     :param context: The context dict under which this timecode is being gotten.
 
-    :return: The :class:`opentime.RationalTime` representation of the
+    :return: The :class: `opentime.RationalTime` representation of the
         timecode.
     """
     if context is not None:
@@ -268,12 +268,12 @@ def _time_from_timecode_element(tc_element, context=None):
 def _track_kind_from_element(media_element):
     """
     Given an FCP XML media sub-element, returns an appropriate
-    :class:`schema.TrackKind` value corresponding to that media type.
+    :class: `schema.TrackKind` value corresponding to that media type.
 
     :param media_element: An XML element that is a child of the ``media`` tag.
 
     :return: The corresponding :class`schema.TrackKind` value.
-    :raises: :class:`ValueError` When the media type is unsupported.
+    :raises: :class: `ValueError` When the media type is unsupported.
     """
     element_tag = media_element.tag.lower()
     if element_tag == "audio":
@@ -309,7 +309,7 @@ def _transition_cut_point(transition_item, context):
     :param transition_item: The XML element for the transition.
     :param context: The context dictionary applying to this transition.
 
-    :return: The :class:`opentime.RationalTime` the transition cuts at.
+    :return: The :class: `opentime.RationalTime` the transition cuts at.
     """
     alignment = transition_item.find('./alignment').text
     start = int(transition_item.find('./start').text)
@@ -522,12 +522,12 @@ def _make_pretty_string(tree_e):
 
 def marker_for_element(marker_element, rate):
     """
-    Creates an :class:`schema.Marker` for the provided element.
+    Creates an :class: `schema.Marker` for the provided element.
 
     :param marker_element: The XML element for the marker.
     :param rate: The rate for the object the marker is attached to.
 
-    :return: The :class:`schema.Marker` instance.
+    :return: The :class: `schema.Marker` instance.
     """
     # TODO: The spec doc indicates that in and out are required, but doesn't
     #       say they have to be locally specified, so is it possible they
@@ -563,7 +563,7 @@ def markers_from_element(element, context=None):
     :param element: An element with one or more ``marker`` child elements.
     :param context: The context for this element.
 
-    :return: A :class:`list` of :class:`schema.Marker` instances attached
+    :return: A :class: `list` of :class: `schema.Marker` instances attached
         to the provided element.
     """
     if context is not None:
@@ -728,7 +728,7 @@ def stack_for_element(self, element, context):
             a ``media`` element.
         :param context: The current parser context.
 
-        :return: A :class:`schema.Stack` of the tracks.
+        :return: A :class: `schema.Stack` of the tracks.
         """
         # Determine the context
         local_context = context.context_pushing_element(element)
@@ -771,7 +771,7 @@ def track_for_element(self, track_element, track_kind, context):
         Given a track element, constructs the OTIO track.
 
         :param track_element: The track XML element.
-        :param track_kind: The :class:`schema.TrackKind` for the track.
+        :param track_kind: The :class: `schema.TrackKind` for the track.
         :param context: The context dict for this track.
         """
         local_context = context.context_pushing_element(track_element)
@@ -844,7 +844,7 @@ def media_reference_for_file_element(self, file_element, context):
         :param file_element: The file xml element.
         :param context: The parent context dictionary.
 
-        :return: An :class:`schema.ExternalReference`.
+        :return: An :class: `schema.ExternalReference`.
         """
         local_context = context.context_pushing_element(file_element)
         media_ref_rate = _rate_from_context(local_context)
@@ -907,7 +907,7 @@ def media_reference_for_effect_element(self, effect_element):
 
         :param effect_element: The effect for the generator.
 
-        :return: An :class:`schema.GeneratorReference` instance.
+        :return: An :class: `schema.GeneratorReference` instance.
         """
         name = _name_from_element(effect_element)
         md_dict = _xml_tree_to_dict(effect_element, {"name"})
@@ -920,10 +920,9 @@ def media_reference_for_effect_element(self, effect_element):
     def item_and_timing_for_element(
         self, item_element, head_transition, tail_transition, context
     ):
-        """
-        Given a track item, returns a tuple with the appropriate OpenTimelineIO
-        schema item as the first element and an
-        :class:`opentime.TimeRange`of theresolved timeline range the clip
+        """ Given a track item, returns a tuple with the appropriate OpenTimelineIO
+        schema item as the first element and an :class: `opentime.TimeRange` of
+        the resolved timeline range the clip
         occupies.
 
         :param item_element: The track item XML node.
@@ -933,8 +932,8 @@ def item_and_timing_for_element(
             after or ``None``.
         :param context: The context dictionary.
 
-        :return: An :class:`core.Item` subclass instance and
-            :class:`opentime.TimeRange` for the item.
+        :return: An :class: `core.Item` subclass instance and
+            :class: `opentime.TimeRange` for the item.
         """
         parent_rate = _rate_from_context(context)
 
@@ -1005,15 +1004,15 @@ def clip_for_element(
         self, clipitem_element, item_range, start_offset, context
     ):
         """
-        Given a clipitem xml element, returns an :class:`schema.Clip`.
+        Given a clipitem xml element, returns an :class: `schema.Clip`.
 
         :param clipitem_element: The element to create a clip for.
         :param item_range: The time range in the timeline the clip occupies.
         :param start_offset: The amount by which the ``in`` time of the clip
             source should be advanced (usually due to a transition).
         :param context: The parent context for the clip.
 
-        :return: The :class:`schema.Clip` instance.
+        :return: The :class: `schema.Clip` instance.
         """
         local_context = context.context_pushing_element(clipitem_element)
 
@@ -1094,7 +1093,7 @@ def clip_for_element(
 
     def effect_from_filter_element(self, filter_element):
         """
-        Given a filter element, creates an :class:`schema.Effect`.
+        Given a filter element, creates an :class: `schema.Effect`.
 
         :param filter_element: The ``filter`` element containing the effect.
 
@@ -1123,7 +1122,7 @@ def transition_for_element(self, item_element, context):
         :param item_element: The element to create a transition for.
         :param context: The parent context for the element.
 
-        :return: The :class:`schema.Transition` instance.
+        :return: The :class: `schema.Transition` instance.
         """
         # start and end times are in the parent's rate
         rate = _rate_from_context(context)
@@ -1162,7 +1161,7 @@ def _backreference_for_item(item, tag, br_map):
     intended to be an opaque data structure and only accessed through this
     function, the structure of data in br_map may change.
 
-    :param item: The :class:`core.SerializableObject` to create an id for.
+    :param item: The :class: `core.SerializableObject` to create an id for.
     :param tag: The tag name that will be used for object in xml.
     :param br_map: The dictionary containing backreference information
         generated so far.
@@ -1286,7 +1285,7 @@ def _append_new_sub_element(parent, tag, attrib=None, text=None):
     """
     Creates a sub-element with the provided tag, attributes, and text.
 
-    This is a convenience because the :class:`SubElement` constructor does not
+    This is a convenience because the :class: `SubElement` constructor does not
     provide the ability to set ``text``.
 
     :param parent: The parent element.
@@ -1330,7 +1329,7 @@ def _build_timecode(time, fps, drop_frame=False, additional_metadata=None):
         auto-determined by rate. This is because the underlying otio timecode
         conversion assumes DFTC based on rate.
 
-    :param time: The :class:`opentime.RationalTime` for the timecode.
+    :param time: The :class: `opentime.RationalTime` for the timecode.
     :param fps: The framerate for the timecode.
     :param drop_frame: If True, generates drop-frame timecode.
     :param additional_metadata: A dictionary with other metadata items like
@@ -1659,7 +1658,7 @@ def _build_generator_effect(clip_item, br_map):
     """
     Builds an effect element for the generator ref on the provided clip item.
 
-    :param clip_item: a clip with a :class:`schema.GeneratorReference` as
+    :param clip_item: a clip with a :class: `schema.GeneratorReference` as
         its ``media_reference``.
     :param br_map: The backreference map.
     """
@@ -1815,7 +1814,7 @@ def _build_timecode_from_metadata(time, tc_metadata=None):
     Makes a timecode element with the given time and (if available)
     ```timecode`` metadata stashed on input.
 
-    :param time: The :class:`opentime.RationalTime` to encode.
+    :param time: The :class: `opentime.RationalTime` to encode.
     :param tc_metadata: The xml dict for the ``timecode`` element populated
         on read.