Fixes/documentation refactor (WIP) (#1810)

* Lots of doc tweaks
* More work on organizational clarity and fixing links.
* Language update

---------

Signed-off-by: Anton Marini <[email protected]>

Author: vade

docs/conf.py

@@ -45,6 +45,12 @@
 
 html_theme = "sphinx_rtd_theme"
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme_options = {
+    'navigation_depth': 1,  # Set the depth to 1 to hide nested headers
+    'collapse_navigation': False,  # Prevents collapsing of nested navigation
+    'sticky_navigation': True,  # Keeps the sidebar navigation in view while scrolling
+}
+
 
 htmlhelp_basename = f'{project.lower()}doc'
 

docs/tutorials/contributing.md docs/fundamentals/contributing.md

@@ -3,6 +3,7 @@
 
 We're excited to collaborate with the community and look forward to the many improvements you can make to OpenTimelineIO!
 
+
 ## Contributor License Agreement
 
 Before contributing code to OpenTimelineIO, we ask that you sign a Contributor License Agreement (CLA).

docs/fundamentals/introduction.md

@@ -0,0 +1,30 @@
+
+# API Introduction
+
+OpenTimelineIO is organized into a few components with separate concerns:
+
+## Python API
+
+The Python API is the preferred API to create and manupulate Timelines, Tracks, Edits, and core schema objects. With the Python API developers can adjust timing, replace media, write adaptors, media linkers, create custom schema additions, and more. 
+
+## Core C++ API
+
+The OTIO Core library is implemented in C++ and provides a cross platform APIs for loading OTIO files, creating Timelines and other core schema objects. 
+
+Developers can interface directly with OTIO and write native cross platform integrations using the C++ API, or use the C++ Api to brige to new languages.
+
+The C++ API can be found at the Core OpenTimelineIO Github hosted by the Academy Software Foundation.
+
+
+## Additional Language Bindings 
+
+The OTIO Community provides language bindings The OpenTimelineIO Python API provides a friendly API for interacting with OTIO objects as well as the Project Adaptor Interface. OTIO Also provides language bindings for 
+
+* [C Bindings](https://github.com/OpenTimelineIO/OpenTimelineIO-C-Bindings)
+* [Java Bindings](https://github.com/OpenTimelineIO/OpenTimelineIO-Java-Bindings)
+* [Swift Bindings](https://github.com/OpenTimelineIO/OpenTimelineIO-Swift-Bindings)
+
+
+## Github Wiki
+
+The OTIO Community also 

docs/tutorials/otio-timeline-structure.md docs/fundamentals/otio-timeline-structure.md

@@ -4,66 +4,101 @@ Welcome to OpenTimelineIO's documentation!
 Overview
 --------
 
-OpenTimelineIO (OTIO) is an API and interchange format for editorial cut information. You can think
-of it as a modern Edit Decision List (EDL) that also includes an API for reading, writing, and
-manipulating editorial data. It also includes a plugin system for translating to/from existing
-editorial formats as well as a plugin system for linking to proprietary media storage schemas.
+The OpenTimelineIO (OTIO) project aims to solve modern VFX and Post Production workflow challenges like conform, project migration, and interchange across software and platforms in a reliable, open source and reproducible manner. 
+
+OpenTimelineIO is:
+
+* :doc:`an ecosystem of video tools and integrations. <intros/integrations>`
+* :doc:`an interchange file format for editorial cut information. <schema/otio-file-format-specification>`
+* :doc:`an cross platform API for timeline data. <cxx/bridges>`
+
+You can think of OTIO as a modern Edit Decision List (EDL) that also includes an API for reading, writing, and
+manipulating editorial data. 
+
+OpenTimelineIO’s API's and language bindings allows application developers to integrate OpenTimelineIO support into their products, 
+and allows studios and developers to build an ecosystem of compatible pipeline tools. 
+
+See our OTIO fundamentals guide, and intros for [Creatives](intros/creatives.md), Pipeline Architects, Integrators and Developers, and our FAQs. 
+
+OpenimelineIO is a [Academy Software Foundation](https://www.aswf.io) incubation project.
 
-OTIO supports clips, timing, tracks, transitions, markers, metadata, etc. but not embedded video or
-audio. Video and audio media are referenced externally. We encourage 3rd party vendors, animation
-studios and visual effects studios to work together as a community to provide adaptors for each
-video editing tool and pipeline.
 
 Links
 ---------
 `OpenTimelineIO Home Page <http://opentimeline.io/>`_
 
 `OpenTimelineIO Discussion Group <https://lists.aswf.io/g/otio-discussion>`_
 
-Quick Start
-------------
+
+Getting Started
+---------------
 .. toctree::
-   :maxdepth: 2
-   :caption: Quick Start
+   :maxdepth: 1
+   :caption: Getting Started
+
+   intros/installation.md
+   intros/creatives.md
+   intros/pipeline.md
+   intros/integrators.md
+   intros/integrations.md
+   intros/community.md
+   intros/roadmap.md
+
+User Tutorials
+--------------
+.. toctree::
+   :maxdepth: 1
+   :caption: User Tutorials
+
+   user_tutorials/sample_media.md
+   user_tutorials/roundtripping.md
+   user_tutorials/animation-shot-frame-ranges
+   user_tutorials/conform-new-renders-into-cut
+   user_tutorials/shots-added-removed-from-cut
 
-   tutorials/quickstart
-   tutorials/otio-env-variables
 
-Tutorials
-------------
+API Fundamentals
+----------------
 .. toctree::
-   :maxdepth: 2
-   :caption: Tutorials
-
-   tutorials/adapters
-   tutorials/architecture
-   tutorials/contributing
-   tutorials/feature-matrix
-   tutorials/otio-timeline-structure
-   tutorials/time-ranges
-   tutorials/otio-filebundles
-   tutorials/write-an-adapter
-   tutorials/write-a-media-linker
-   tutorials/write-a-hookscript
-   tutorials/write-a-schemadef
-   tutorials/spatial-coordinates
-   tutorials/developing-a-new-schema
-   tutorials/versioning-schemas
-
-Use Cases
-------------
+   :maxdepth: 1
+   :caption: API Fundamentals
+   
+   fundamentals/introduction
+   fundamentals/otio-timeline-structure
+   fundamentals/time-ranges
+   fundamentals/spatial-coordinates
+   fundamentals/contributing.md
+
+
+Python Fundamentals
+-------------------
 .. toctree::
-   :maxdepth: 2
-   :caption: Use Cases
+   :maxdepth: 1
+   :caption: Python Fundamentals
+
+   python/architecture
+   python/feature-matrix
+   python/adapters.md
+   python/otio-plugins.md 
+   python/otio-env-variables.md 
+
+
+Python Tutorials
+-------------------
+.. toctree::
+   :maxdepth: 1
+   :caption: Python Tutorials
 
-   use-cases/animation-shot-frame-ranges
-   use-cases/conform-new-renders-into-cut
-   use-cases/shots-added-removed-from-cut
+   python-tutorials/write-an-adapter
+   python-tutorials/write-a-media-linker
+   python-tutorials/write-a-hookscript
+   python-tutorials/write-a-schemadef
+   python-tutorials/developing-a-new-schema
+   python-tutorials/versioning-schemas
 
 API References
 --------------
 
-
 .. toctree::
    :maxdepth: 3
    :caption: API References
@@ -74,25 +109,29 @@ API References
    cxx/cxx.md
    cxx/older.md
 
-Schema Reference
-----------------
+Schema References
+-----------------
 
 .. toctree::
    :maxdepth: 2
-   :caption: Schema Reference
+   :caption: Schema References
 
-   tutorials/otio-file-format-specification
-   tutorials/otio-serialized-schema
-   tutorials/otio-serialized-schema-only-fields
+   schema/otio-filebundles
+   schema/otio-file-format-specification
+   schema/otio-serialized-schema
+   schema/otio-serialized-schema-only-fields
 
-Autogenerated Plugin Reference
-------------------------------
+
+Utilities
+---------
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Plugins Reference
+   :maxdepth: 1
+   :caption: Utilities
 
-   tutorials/otio-plugins.md
+   utilities/otio_convert_quickstart.md
+   utilities/otio_viewer_quickstart.md
+   utilities/raven.md
 
 
 Indices and tables

docs/tutorials/spatial-coordinates.md docs/fundamentals/spatial-coordinates.md

@@ -0,0 +1,10 @@
+# Community
+
+Join the OpenTimelineIO community and particpate in 
+
+* [OpenTimelineIO Slack](https://academysoftwarefdn.slack.com/messages/CMQ9J4BQC)
+* [OpenTimelineIO Discussion Group ](https://lists.aswf.io/g/otio-discussion)
+* [Core Github](https://github.com/AcademySoftwareFoundation/OpenTimelineIO/)
+* [Community Github Organitation](https://github.com/OpenTimelineIO/)
+* Technical Steering Committee (TSC) meetings are open the the public. See Slack and the Discussio group for meeting timing and links.
+* [Past TSC Metting Presentations](https://github.com/AcademySoftwareFoundation/OpenTimelineIO/wiki/Presentations)

docs/tutorials/time-ranges.md docs/fundamentals/time-ranges.md

@@ -0,0 +1,11 @@
+# For Creatives
+
+OpenTimelineIO can help solve a variety of conform, project interchange, studio pipelines, archival and other workflows.
+
+The best place to start is our [Workflow tutorials and Example files](/user_tutorials/sample_media.md) which contain media as well as .otio files. 
+
+[OpenTimelineIO support is available with the following integrations](integrations.md) allowing you to export otio files and import them (with some caveats).
+
+If you don’t see your preferred software listed in the integrations, check for [available adaptors](/python/adapters.md) and use the project conversion tool `otioconvert`. This allows for workflows via project conversion. S
+
+You can also download Raven - a free cross platform timeline visualizer. 

docs/index.rst

@@ -0,0 +1,24 @@
+# Installation
+
+There are various ways of working with OpenTimelineIO, from simply importing and exporting otio files in supported software, using the OpenTimelineIO Python API to automate workflows and writing custom project adapators, to native application integration and working with the core C++ library or language bindings. 
+
+
+## Software Integrations
+
+For most users, there is nothing to install to use OpenTimelineIO. OpenTimelineIO is available in many video software packages today, allowing for importing or exporting `.otio`, `.otiod` or `.otioz` files with no additional requirements. 
+
+[See a list available software integrations](integrations.md).
+
+## For Developers
+
+[Please see our developer introduction documentation.](/fundamentals/introduction.md)
+
+## Utility Software 
+
+The OTIO project and wider community provides various additional software:
+
+* OTIO Viewer
+* OTIO Util
+* Raven
+
+

docs/intros/community.md

@@ -0,0 +1,47 @@
+# Available Integrations
+
+OpenTimelineIO is used in a variety of software and projects. If you know of any, feel free to add them to this list (in alphabetical order).
+
+
+## Playback/Review Applications:
+- [Cezanne](http://cezanne.ahead.io/cezanne-studio/) - Media player and review tool.
+- [ftrack cineSync Play](https://www.ftrack.com/en/cinesync-play) - Frame-accurate playback & review & tool.
+- [Hiero](https://www.foundry.com/products/nuke-family/hiero) - Multi-shot management, conform, editorial, review and distribution workflows tool.
+- [mrViewer](https://mrviewer.sourceforge.io/) - flipbook, video and audio player, with [OTIO support demonstrated here](https://www.youtube.com/watch?v=yXaYj406xiM).
+- [OpenRV](https://github.com/AcademySoftwareFoundation/OpenRV) - A digital review tool for film, TV, and games
+- [RV](https://www.shotgridsoftware.com/rv/) - The commercial version of OpenRV (as of release "2022.0")
+- [tlRender](https://github.com/darbyjohnston/tlRender) - An open source library for building playback and review applications for visual effects, film, and animation.
+
+## Non-Linear Video Editors:
+- [Adobe Premiere Pro](https://www.adobe.com/products/premiere.html) - Premiere Pro v25.1 (Beta) supports OTIO and OTIOz import and export.
+- [Avid MediaComposer](https://www.avid.com/media-composer) - Media Composer [v2024 supports a public preview of OTIO support](https://resources.avid.com/SupportFiles/attach/WhatsNew_MediaComposer_v24.6.pdf)
+- [DaVinci Resolve](https://www.blackmagicdesign.com/products/davinciresolve) - DaVinci
+Resolve 18 - supports OTIO and OTIOZ import/export in both the free and paid versions of the app.
+- [Kdenlive](https://kdenlive.org/en/about/) - KDE Non-Linear Video Editor - supports OTIO as of [version 20.04](https://kdenlive.org/en/2020/04/kdenlive-20-04-is-out/)
+- [Olive](https://olivevideoeditor.org/) Free open-source non-linear video editor - supports OTIO [import](https://github.com/olive-editor/olive/blob/master/app/task/project/loadotio/loadotio.cpp) and [export](https://github.com/olive-editor/olive/blob/master/app/task/project/saveotio/saveotio.cpp).
+
+## Other Applications/Plugins/etc:
+
+- [Altera](https://cine.dev/) - Metadata Management tool (coming soon).
+- [Blender VSE IO](https://gitlab.com/superprod/stax_suite/vse_io) - Blender Video Sequence Editor add-on for importing and exporting various editorial interchange formats.
+- [EditReader](http://www.editreader.co.uk/) - Animatic and animation production timeline manager, tracks timeline changes etc. Supports OTIO input and output in version 4.
+- [hiero-otio](https://github.com/apetrynet/hiero-otio/) - Import and export OpenTimelineIO files directly in Hiero or Nuke Studio.
+- [Magla](https://github.com/magnetic-lab/magla) - A free SQL-powered data pipeline for animation and visual-effects freelancers and studios, with an emphasis on dynamically generated OTIO timelines.
+- [Matchbox](https://www.thecargocult.nz/products/matchbox) - Change Management solution, aimed at anyone working in post production - compares two versions of a reel or episode and finds every cut change, VFX tweak or dialog slip.
+- [maya-otio](https://github.com/rosborne132/maya-otio) - Maya plugin to import and export OpenTimelineIO files directly into scenes.
+- [Nuke Studio](https://www.foundry.com/products/nuke-family/nuke-studio) - Multi-shot management, editorial and compositing tool.
+- [OpenTimelineIO-Swift-Bindings](https://github.com/OpenTimelineIO/OpenTimelineIO-Swift-Bindings) - bindings for the Swift programming language.
+- [OpenTimelineIO-Unreal-Plugin](https://github.com/OpenTimelineIO/OpenTimelineIO-Unreal-Plugin) - Plugin for Unreal Engine that provides a configurable framework and actions for mapping between an OpenTimelineIO timeline and a UE level sequence hierarchy.
+- [otio-cdl-adapter](https://github.com/josh-mission/otio-cdl-adapter) - Simple OTIO adapter for exporting .cdl files for each clip in an OTIO instance.
+- [otio-cookelensmetadata](https://github.com/reinecke/otio-cookelensmetadata) - A proof-of concept OpenTimelineIO adapter for the Cooke LMF lens metadata format.
+- [otio-drp-adapter](https://pypi.org/project/otio-drp-adapter/) - OTIO adapter for reading .drp files generated by the blackmagic ATEM ISO video mixer (https://www.blackmagicdesign.com/products/atemmini)
+- [otio-mlt-adapter](https://pypi.org/project/otio-mlt-adapter/) - OTIO adapter for writing [MLT Multimedia Framework](https://www.mltframework.org/) files.
+- [otio-premiereproject](https://github.com/splidje/otio-premiereproject) - OpenTimelineIO adapter for at least reading Premiere .prproj files.
+- [protio](https://github.com/boredstiff/protio) - Premiere Pro OTIO Plugin
+- [Pype](https://github.com/pypeclub/pype) - Multi-platform open-source pipeline built around the Avalon platform, expanding it with extra features and integrations. Pype connects asset database, project management and time tracking into a single modular system.
+- [resolve-otio](https://github.com/eric-with-a-c/resolve-otio) - An OpenTimelineIO plugin for DaVinci Resolve.
+- [Shot Manager](https://github.com/ubisoft/shotmanager) - Shot Manager - Blender Add-on from Ubisoft.
+- [speech-edit](https://github.com/ethan-ou/speech-edit) - Automatically cut videos (especially vlogs and talking-head videos) using speech detection.
+- [UnrealOTIOExporter](https://github.com/mvanneutigem/UnrealOtioExporter) - Movie Render Queue Setting for Unreal (see also [this tutorial/article by the author](https://www.artstation.com/mvanneutigem/blog/y7wQ/creating-a-custom-movie-render-queue-setting-for-unreal))
+- [Video Tracks](https://github.com/ubisoft/videotracks) - Video Tracks - Blender Add-on from Ubisoft.
+- [SG OTIO](https://github.com/GPLgithub/sg-otio) - An OpenTimelineIO ShotGrid Python Library