AcademySoftwareFoundation · MrFruitDude · Mar 10, 2026
diff --git a/README.md b/README.md
@@ -1,16 +1,17 @@
-# Welcome to xSTUDIO - v1.1.0
+# Welcome to xSTUDIO 1.1.0
 
 xSTUDIO is a media playback and review application designed for professionals working in the film and TV post production industries, particularly the Visual Effects and Feature Animation sectors. xSTUDIO is focused on providing an intuitive, easy to use interface with a high performance playback engine at its core and C++ and Python APIs for pipeline integration and customisation for total flexibility.
 
-This codebase will build version 1.0.0 (alpha) of xstudio. There are some known issues that are currently being worked on:
+This repository builds xSTUDIO `v1.1.0`. The top-level documentation has been refreshed to match the current source tree and is split between the user guide in `docs/user_docs` and the developer reference in `docs/reference`.
+
+There are still some known issues that are currently being worked on:
 
 * Moderate audio distortion on playback (Windows only)
-* Ueser Documentation and API Documentation is badly out-of-date.
 * Saved sessions might not restore media correctly (Windows only)
 
 ## Building xSTUDIO
 
-This release of xSTUDIO can be built on various Linux flavours, Microsoft Windows and MacOS. We provide comprehensive build steps here.
+This release of xSTUDIO can be built on various Linux distributions, Microsoft Windows, and macOS. We provide comprehensive build steps here.
 
 ### Building xSTUDIO for Linux
 
@@ -23,10 +24,10 @@ This release of xSTUDIO can be built on various Linux flavours, Microsoft Window
 
 * [Windows](docs/reference/build_guides/windows.md)
 
-### Building xSTUDIO for MacOS
+### Building xSTUDIO for macOS
 
-* [MacOS](docs/reference/build_guides/macos.md)
+* [macOS](docs/reference/build_guides/macos.md)
 
-### Documentation Note
+### Documentation
 
-Note that the xSTUDIO user guide is built with Sphinx using the Read-The-Docs theme. The package dependencies for building the docs can be challenging to install so we instead include the fully built docs as part of xSTUDIO's repo, as well as the source for building the docs. Our build set-up by default disables the building of the docs to make life easy!
+xSTUDIO's documentation is built with Sphinx and Doxygen. The source lives under `docs/`, with end-user workflows in `docs/user_docs` and build/API reference material in `docs/reference`. The standard build keeps documentation disabled by default; enable it with `-DBUILD_DOCS=ON` if you want to generate the HTML site locally.
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,8 +3,18 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to xSTUDIO's documentation!
-===================================
+Welcome to xSTUDIO 1.1.0
+========================
+
+xSTUDIO is a playback, review, and pipeline-integration application for VFX,
+animation, and post-production workflows.
+
+This documentation set is split into two parts:
+
+* :ref:`user_docs` for day-to-day playback, review, timeline, and note-taking
+  workflows.
+* :ref:`reference_docs` for build instructions plus the C++ and Python API
+  surfaces exposed by the current source tree.
 
 |
 |
@@ -30,4 +40,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-
diff --git a/docs/reference/api/index.rst b/docs/reference/api/index.rst
@@ -1,17 +1,19 @@
 .. _api_:
 
-.. note::
-    August 2025: The C++ API documentation is WIP. For developers interested in developing C++ we encourage you to look over the source code of xSTUDIO's native plugins. These are to be found inside the **src/plugin** folder from the root of the xSTUDIO source repo.
+C++ API
+========
 
-    Many of xSTUDIO's important features have been implemented as plugins. Primarily this approach was taken to ensure that xSTUDIO can be expanded and modified in the future without needing to re-work core components of the source code. In addition this both ensures that the C++ plugin API is well-developed and flexible and also provides a rich set of reference implementations for new developers to begin working from for their own projects.
+The C++ side of xSTUDIO is structured around public headers and plugin
+extension points. The generated API pages below focus on the headers that
+define the current plugin surface and shared utility types.
 
-    Nevertheless, we will strive to improve the API Class documentation here over the coming months.
+For concrete implementations, inspect the matching source under `src/plugin`
+alongside the header docs.
 
-API
-===
 .. toctree::
     :maxdepth: 2
 
+    overview
     plugin
     utility
     enums
diff --git a/docs/reference/api/overview.rst b/docs/reference/api/overview.rst
@@ -0,0 +1,51 @@
+.. _api_overview:
+
+C++ API Overview
+================
+
+xSTUDIO's C++ API is plugin-first. The public headers in `include/xstudio`
+define the core extension points, while concrete examples live in `src/plugin`.
+
+What This Reference Covers
+--------------------------
+
+The pages in this section expose the public headers that are most useful when
+extending xSTUDIO:
+
+* `plugin_manager/plugin_base.hpp` for `StandardPlugin` and viewport-related
+  hooks.
+* `ui/viewport/video_output_plugin.hpp` for off-screen render and video-output
+  integrations.
+* `colour_pipeline/colour_pipeline.hpp` for display and colour-management
+  plugins.
+* `ui/viewport/viewport_layout_plugin.hpp` and
+  `plugin_manager/hud_plugin.hpp` for compare layouts and HUD or overlay
+  plugins.
+* `data_source/data_source.hpp`, `media_reader/media_reader.hpp`,
+  `media_metadata/media_metadata.hpp`, and `media_hook/media_hook.hpp` for
+  ingest and metadata customization.
+* `utility/*.hpp` for the shared value types, JSON helpers, frame and timecode
+  types, UUID helpers, and other support classes used throughout the API.
+
+Reference Implementations
+-------------------------
+
+The fastest way to understand the API is usually to read the shipped plugins
+alongside the header docs:
+
+* `src/plugin/colour_pipeline/ocio` shows the built-in OCIO integration.
+* `src/plugin/viewport_layout/*` contains the default, grid, composite, and
+  wipe layout implementations.
+* `src/plugin/hud/*` contains concrete HUD overlays such as pixel probe and EXR
+  data window.
+* `src/plugin/media_reader/*` and `src/plugin/media_metadata/*` contain file
+  format readers and metadata readers.
+* `src/plugin/data_source/*` contains data-source integrations, including the
+  DNEG-specific examples.
+
+Reading Strategy
+----------------
+
+If you are new to the codebase, start with `StandardPlugin`, then move to the
+specific plugin type you need. After that, inspect the matching implementation
+under `src/plugin` and the relevant utility headers used by that plugin.
diff --git a/docs/reference/api/plugin.rst b/docs/reference/api/plugin.rst
@@ -5,6 +5,16 @@ StandardPlugin
 .. doxygenfile:: plugin_manager/plugin_base.hpp
    :project: xStudio
 
+HUDPluginBase
+=============
+.. doxygenfile:: plugin_manager/hud_plugin.hpp
+   :project: xStudio
+
+ViewportLayoutPlugin
+====================
+.. doxygenfile:: ui/viewport/viewport_layout_plugin.hpp
+   :project: xStudio
+
 VideoOutputPlugin
 =================
 .. doxygenfile:: ui/viewport/video_output_plugin.hpp
@@ -14,3 +24,23 @@ ColourPipelinePlugin
 ====================
 .. doxygenfile:: colour_pipeline/colour_pipeline.hpp
    :project: xStudio
+
+DataSourcePlugin
+================
+.. doxygenfile:: data_source/data_source.hpp
+   :project: xStudio
+
+MediaReaderPlugin
+=================
+.. doxygenfile:: media_reader/media_reader.hpp
+   :project: xStudio
+
+MediaMetadataPlugin
+===================
+.. doxygenfile:: media_metadata/media_metadata.hpp
+   :project: xStudio
+
+MediaHookPlugin
+===============
+.. doxygenfile:: media_hook/media_hook.hpp
+   :project: xStudio
diff --git a/docs/reference/build_guides/index.rst b/docs/reference/build_guides/index.rst
@@ -4,12 +4,19 @@
 xSTUDIO Build Guides
 ####################
 
-At the time of writing these notes (August 2025) xSTUDIO is publically available as *source code* only and as such, to obtain the application, it must be built from the source. 
+xSTUDIO is currently distributed from source in this repository, so building
+from source is the standard way to obtain the application.
 
 Post Production Studios and Other Organisations
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Many VFX and Animation studios, especially larger ones, typically have technical teams who have expertise in building software from source code. For such teams with expertise in building and deploying software packages we expect that building xstudio should be straightforward. The build guides below should provide valuable reference. Note that version 1.X of xSTUDIO has been developed against the VFX Reference Platform 2024 standard plus a small set of open source packages/libraries that are easily obtained or built on any platform. A :ref:`list of these build dependencies <dependencies>` is provided for your convenience.
+Many VFX and animation studios, especially larger ones, typically have
+technical teams with experience building software from source. For those teams,
+the guides below should provide a practical reference. xSTUDIO 1.1.x is
+developed against the VFX Reference Platform 2024 plus a small set of open
+source packages and libraries that are easily obtained or built on any
+platform. A :ref:`list of these build dependencies <dependencies>` is provided
+for convenience.
 
 Individual Users
 ^^^^^^^^^^^^^^^^
@@ -27,4 +34,4 @@ If you have any **questions** reach out on the ASWF Slack in the `#ori-xstudio-d
     rocky_linux_9_1
     ubuntu_22_04
     centos_7
-    dependencies
+    dependencies
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -1,8 +1,18 @@
-.. _python_api_:
+.. _reference_docs:
 
 xSTUDIO Reference
 =================
 
+xSTUDIO's reference material is aimed at developers, technical directors, and
+pipeline engineers.
+
+This section is split into three parts:
+
+* :ref:`build_guides` for platform-specific build and dependency notes.
+* :ref:`api_` for the public C++ headers and plugin extension points.
+* :ref:`python_api_` for the Python connection layer, session wrappers, and
+  plugin helpers shipped in `python/src/xstudio`.
+
 .. toctree::
     :maxdepth: 2
     :glob: