Skip to content
Permalink
Browse files

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
  • Loading branch information...
ssteinbach committed Aug 7, 2019
1 parent f38c21e commit c5bc94d61a77eadb793a79805611358dd653945a
@@ -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
@@ -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
@@ -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)
@@ -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
------------------

@@ -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

This file was deleted.

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

dependencies:
- cmake
@@ -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',
@@ -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.

0 comments on commit c5bc94d

Please sign in to comment.
You can’t perform that action at this time.