Full update to xSTUDIO Documentation

Signed-off-by: Ted Waine <[email protected]>

Author: tedwaine

CMakeLists.txt

@@ -197,7 +197,7 @@ if (USE_VCPKG)
     message(FATAL_ERROR "Failed to ensurepip.")
   else()
     execute_process(
-      COMMAND "${Python_EXECUTABLE}" -m pip install setuptools sphinx breathe sphinx-rtd-theme OpenTimelineIO-Plugins importlib_metadata zipp
+      COMMAND "${Python_EXECUTABLE}" -m pip install setuptools sphinx breathe sphinx-rtd-theme OpenTimelineIO-Plugins importlib_metadata myst-parser zipp
       RESULT_VARIABLE PIP_RESULT
     )
     if(PIP_RESULT)

CMakePresets.json

@@ -10,7 +10,7 @@
         "Qt6_DIR": "/Users/tedwaine/Qt6/6.5.3/macos/lib/cmake/Qt6",
         "CMAKE_INSTALL_PREFIX": "xstudio_install",
         "X_VCPKG_APPLOCAL_DEPS_INSTALL": "ON",
-        "BUILD_DOCS": "OFF",
+        "BUILD_DOCS": "ON",
         "USE_VCPKG": "ON"
       }
     },

README.md

@@ -1,34 +1,21 @@
-# Welcome to xSTUDIO - v1.0.0 (alpha)
+# Welcome to xSTUDIO - v1.0.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:
+## xSTUDIO Documentation
 
-* 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)
+You can browse xSTUDIO's user and reference documentation [here](share/docs/index.html).
 
 ## Building xSTUDIO
 
-This release of xSTUDIO can be built on various Linux flavours and Windows 10 and 11. MacOS compatibility is not available yet but this work is on the roadmap for early 2025.
+This release of xSTUDIO can be built on various Linux flavours, MacOS and Windows 10 and 11. Comprehensive build instructions are available as follows:
 
-We provide comprehensive build steps for 4 of the most popular distributions.
-
-### Building xSTUDIO for Linux
-
-* [Linux Generic](docs/build_guides/linux_generic.md) 
-* [CentOS 7](docs/build_guides/centos_7.md)
-* [Rocky Linux 9.1](docs/build_guides/rocky_linux_9_1.md)
-* [Ubuntu 22.04](docs/build_guides/ubuntu_22_04.md)
-
-### Building xSTUDIO for Windows
-
-* [Windows](docs/build_guides/windows.md)
-
-### Building xSTUDIO for MacOS
-
-* [MacOS](docs/build_guides/macos.md)
+* [Windows](docs/reference/build_guides/windows.md)
+* [MacOS](docs/reference/build_guides/macos.md)
+* [Linux Generic using VCPKG](docs/reference/build_guides/linux_generic.md) 
+* [Rocky Linux 9.1](docs/reference/build_guides/rocky_linux_9_1.md)
+* [Ubuntu 22.04](docs/reference/build_guides/ubuntu_22_04.md)
 
 ### Documentation Note
 
-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!
+Note that the xSTUDIO user guide is built with Sphinx using the Read-The-Docs theme and API documentation is auto-generated using the Breathe plugin for Sphinx. The package dependencies for building the docs can be challenging to build/obtain/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!

docs/CMakeLists.txt

@@ -26,8 +26,11 @@ endforeach(target_var)
 set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR})
 set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen)
 set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
+
+# TODO: output config should be somewhere in CMAKE_CURRENT_BINARY_DIR, but
+# sphinx expects config.py to be in the docs source dir
 set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
-set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile)
 set(CONFFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in)
 set(CONFFILE_OUT ${CMAKE_CURRENT_SOURCE_DIR}/conf.py)
 
@@ -66,20 +69,9 @@ add_custom_target(Sphinx ALL
                   -D version=${PROJECT_VERSION}
                   -D release=${PROJECT_VERSION}
                   ${SPHINX_SOURCE} ${SPHINX_BUILD}
-                  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
                   COMMENT "Generating documentation with Sphinx")
 
-set(USER_DOCS_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/user_docs)
-set(USER_DOCS_BUILD ${CMAKE_CURRENT_BINARY_DIR}/../bin/user_docs)
-
-add_custom_target(UserDocs ALL
-				  COMMAND ${SPHINX_EXECUTABLE} -q
-				  -D version=${PROJECT_VERSION}
-				  -D release=${PROJECT_VERSION}
-				  ${USER_DOCS_SOURCE} ${USER_DOCS_BUILD}
-				  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-                  COMMENT "Generating user documentation with Sphinx")
-
 if (APPLE)
 install(DIRECTORY ${SPHINX_BUILD}/ DESTINATION ${CMAKE_BINARY_DIR}/xSTUDIO.app/Contents/Resources/docs)
 else()