AcademySoftwareFoundation · czerouni · Sep 21, 2024 · Sep 21, 2024 · Sep 21, 2024 · Sep 26, 2024
diff --git a/docs/concepts/_index.rst b/docs/concepts/_index.rst
@@ -9,4 +9,4 @@ Concepts
    :caption: Concepts
 
    overview/overview
-   publications/publications
+   publications/publications
diff --git a/docs/concepts/overview/internal_architecture.rst b/docs/concepts/overview/internal_architecture.rst
@@ -2,8 +2,8 @@
   SPDX-License-Identifier: CC-BY-4.0
   Copyright Contributors to the OpenColorIO Project.
 
-Internal Architecture Overview
-==============================
+Internal Architecture
+=====================
 
 .. warning::
     This section is from OCIO v1 and has not been updated yet.
@@ -212,11 +212,8 @@ An Example
 Let us consider the internal steps when getProcessor() is called to convert from ColorSpace
 'adx10' to ColorSpace 'aces':
 
-* The first step is to turn this ColorSpace conversion into an ordered list of transforms.
-We do this by creating a single list of the conversions from 'adx10' to reference, and then
-adding the transforms required to go from reference to 'aces'.
-* The Transform list is then converted into a list of ops.  It is during this stage luts,
-are loaded, etc.
+* The first step is to turn this ColorSpace conversion into an ordered list of transforms.  We do this by creating a single list of the conversions from 'adx10' to reference, and then adding the transforms required to go from reference to 'aces'.
+* The Transform list is then converted into a list of ops.  It is during this stage luts, are loaded, etc.
 
 
 CPU CODE PATH

diff --git a/docs/concepts/overview/overview.rst b/docs/concepts/overview/overview.rst
@@ -9,6 +9,8 @@ Overview
 
 .. include:: introduction.rst
 
+.. include:: configuration_files.rst
+
 .. include:: internal_architecture.rst
 
 .. include:: glossary.rst
diff --git a/docs/concepts/publications/publications.rst b/docs/concepts/publications/publications.rst
@@ -7,11 +7,11 @@
 Presentations & Publications
 ============================
 
-* ASWF Open Source Days 2023 `video <https://www.youtube.com/watch?v=y-oq693Wl8g>`_
+* ASWF Open Source Days 2023 `video <https://www.youtube.com/watch?v=y-oq693Wl8g>`__
 
-* OCIO wins the Pipeline Tool award at DigiPro 2022! `video <https://vimeo.com/742052701>`_
+* OCIO wins the Pipeline Tool award at DigiPro 2022! `video <https://vimeo.com/742052701>`__
 
-* ASWF Open Source Days 2022 `video <https://www.youtube.com/watch?v=WzFlz1HeNdI>`_
+* ASWF Open Source Days 2022 `video <https://www.youtube.com/watch?v=WzFlz1HeNdI>`__
 
 * HPA Tech Retreat 2022 "Color Processing with OCIO v2 and the Academy/ASC Common LUT Format"
   `Slides & Tutorial <https://drive.google.com/drive/folders/1ZRTIYE6kFb-7sTUtYIYFNJndhY6tmJee?usp=share_link>`_
@@ -20,14 +20,14 @@ Presentations & Publications
   `article <https://www.hollywoodreporter.com/movies/movie-news/hpa-engineering-excellence-award-recipients-announced-1234995410/>`_
 
 * SIGGRAPH 2021 course "Color management with OpenColorIO V2" 
-  `video <https://vimeo.com/689093714>`__  `PDF <https://drive.google.com/file/d/1v37Bz7s1wbJNg-ULsBqnGPA9h7pWNfhU/view?usp=share_link>`__  `ACM <https://dl.acm.org/doi/10.1145/3450508.3464600>`_
+  `video <https://vimeo.com/689093714>`__  `PDF <https://drive.google.com/file/d/1v37Bz7s1wbJNg-ULsBqnGPA9h7pWNfhU/view?usp=share_link>`__  `ACM <https://dl.acm.org/doi/10.1145/3450508.3464600>`__
 
-* ASWF Open Source Days 2021 `video <https://youtu.be/FSzLwSTJjWo>`_
+* ASWF Open Source Days 2021 `video <https://youtu.be/FSzLwSTJjWo>`__
 
-* DigiPro 2020 "The ASWF takes OpenColorIO to the Next Level" `video <https://vimeo.com/458011669>`__  `PDF <https://drive.google.com/file/d/1y_0ZEftivHH0zoKwvKZx3gH_u_cDm1bD/view?usp=sharing>`__  `ACM <https://dl.acm.org/doi/abs/10.1145/3403736.3403942>`_
+* DigiPro 2020 "The ASWF takes OpenColorIO to the Next Level" `video <https://vimeo.com/458011669>`__  `PDF <https://drive.google.com/file/d/1y_0ZEftivHH0zoKwvKZx3gH_u_cDm1bD/view?usp=sharing>`__  `ACM <https://dl.acm.org/doi/abs/10.1145/3403736.3403942>`__
 
-* ASWF Open Source Days 2020 `video <https://www.youtube.com/watch?v=7e0SSka8Ar8>`_
+* ASWF Open Source Days 2020 `video <https://www.youtube.com/watch?v=7e0SSka8Ar8>`__
 
-* ASWF Open Source Days 2019 `video <https://youtu.be/L5dpFtgZuhQ>`_
+* ASWF Open Source Days 2019 `video <https://youtu.be/L5dpFtgZuhQ>`__
 
 * `Cinematic Color <http://cinematiccolor.org/>`_
diff --git a/docs/conf.py b/docs/conf.py
@@ -86,7 +86,15 @@
 }
 
 master_doc = "index"
-exclude_patterns = ["build", "*-prefix", "api/python", "site"]
+exclude_patterns = [
+  "INSTALL.md",
+  "README*",
+  "CHANGELOG.md",
+  "build",
+  "*-prefix",
+  "api/python",
+  "site"
+]
 
 rst_prolog = """
 .. |OCIO| replace:: *OCIO*
@@ -122,6 +130,7 @@
 # expandvars
 expandvars_define = {
     "PYDIR": "frozen" if RTD_BUILD else "src",
+    #"PYDIR": "frozen",
     "OCIO_NAMESPACE": ocio_namespace,
 }
 

diff --git a/docs/guides/contributing/documentation_guidelines.rst b/docs/guides/contributing/documentation_guidelines.rst
@@ -22,23 +22,35 @@ Installation of requirements
 Scripts are available, for each platform, to install the documentation 
 requirements.
 
-The ``install_docs_env.sh`` script in the share/ci/scripts/<Platform> directory
+The ``install_docs_env.sh`` script in the ``share/ci/scripts/<Platform>`` directory
 will install the Python-related requirements for building the documentation
 (Sphinx, six, testresources, recommonmark, sphinx-press-theme, sphinx-tabs,
 and breathe) and Doxygen.  
 
+**Note:** If you are on Linux using yum and don't already have Doxygen installed, you will have to
+uncomment the relevant line in ``share/ci/scripts/linux/yum/install_docs_env.sh``
+
 Use GitBash (`provided with Git for Windows <https://gitforwindows.org/>`_) to 
 execute the script on Windows.
 
 Python 3 is required to build the documentation. If you have multiple Python
 installs you'll need to make sure pip and CMake find the correct version. You 
 can manually inform CMake of which to use by adding this option to the below 
-`cmake` command, which configures the documentation build:
+`cmake` command, which configures the documentation build::
 
     -DPython_ROOT=<Path to Python 3 root directory>
 
-For the Python packages, ensure their locations are in your ``PYTHONPATH`` 
-environment variable prior to configuring the build.
+You need to make sure these Python package locations are in your ``PYTHONPATH``
+environment variable prior to configuring the build. A good way to accomplish this is
+with a virtual environment, which would look like::
+
+    $ python3 -m venv venv
+    $ source venv/bin/activate
+    $ share/ci/scripts/<platform>/install_docs_env.sh
+    $ export PYTHONPATH=</path/to>/venv/lib/python<version>/site-packages
+
+Obviously, adjust for specific paths and python versions. Also, the above assumes a ``bash``
+environment - the commands may be slightly different for other shells.
 
 Building the docs
 *****************
@@ -58,25 +70,32 @@ Initial run::
 
 Then after each change you wish to preview::
 
-    $ cmake -D OCIO_BUILD_DOCS=ON .. && make docs
+    $ cmake -D OCIO_BUILD_DOCS=ON ../ && make docs
+
+Tip: 
+    The ``-j`` option to ``make`` is your friend, eg, ``make -j 8`` will make things go much faster.
+    The exact number will depend on the resources of your particular machine. The ``nproc`` command (linux) will help you decide.
 
 Updating the Python docs
 ************************
 
 If a contributor makes changes to any part of OCIO which affects the Python API docs 
 (so, public headers, Python bindings, any documentation process code, etc.) they should 
-do a local build with the new CMake option -DOCIO_BUILD_FROZEN_DOCS=ON, and add the 
-modified rST files under docs/api/python/frozen to their PR.
+do a local build with the new CMake option -DOCIO_BUILD_FROZEN_DOCS=ON::
+
+    $ cmake -DOCIO_BUILD_FROZEN_DOCS=ON ../
+
+and add the modified rST files found under ``docs/api/python/frozen`` to their PR.
 
-Note: If you run the scripts on Linux, the freezing process should work well.  On other 
+**Note:** If you run the scripts on Linux, the freezing process should work well.  On other 
 platforms, the process may sometimes make spurious deltas to rST files unrelated to your 
 changes.  Please don't add these files to your PR.
 
 The OCIO conf.py module has a switch that detects when docs are being built on GH Actions 
-(CI env var == true) it will backup the frozen folder to a sibling backup folder on Sphinx 
-init, and following Sphinx build completion will do a file-by-file comparison of the new 
-frozen and the backup folders. If there are differences, the CI job may fail with an error 
-explaining where the differences were found and with instructions on how to fix them.
+(CI env var == true); in that case it will backup the "frozen" folder to a sibling backup
+folder on Sphinx init, and following Sphinx build completion will do a file-by-file comparison
+of the new "frozen" and backup folders. If there are differences, the CI job may fail with
+an error explaining where the differences were found and with instructions on how to fix them.
 
 The conf.py also has a switch that detects when it is being run on RTD, and in that case 
 will itself run Doxygen to generate the XML needed by breathe prior to building the docs, 
@@ -88,14 +107,14 @@ nothing more. Right now that only works when the READTHEDOCS env var == True, bu
 be easily exposed another way if needed.
 
 These features required several custom Sphinx extensions tuned for our project which are
-located under share/docs.
+located under ``share/docs``.
 
 Building the docs -- Excluding the API docs
 *******************************************
 
 If you don't need to build the API documentation, there is a quick and dirty way to 
 do a docs build.  This approach does not need to compile the C++ code but is not ideal
-since it modifies files in the source directory rather than the build directory:
+since it modifies files in the source directory rather than the build directory::
 
     export READTHEDOCS=True
     cd docs  (in the source directory)

diff --git a/docs/guides/contributing/doxygen_style_guide.rst b/docs/guides/contributing/doxygen_style_guide.rst
@@ -67,8 +67,8 @@ Where possible please try to split the tag and names from the descriptive text.
      *
      * Compresses an input string using the foobar algorithm.
      *
-     * \param
-     *      Uncompressed The input string.
+     * \param uncompressed
+     *      The input string.
      * \return
      *      A compressed version of the input string.
      */

diff --git a/docs/guides/using_ocio/compatible_software.rst b/docs/guides/using_ocio/compatible_software.rst
@@ -335,7 +335,7 @@ Website : `<https://github.com/aferrero2707/PhotoFlow>`__
 
 
 Photoshop (beta)
-*********
+****************
 OCIO can be enabled via a technology preview checkbox in preferences. For more details see `OpenColorIO and 32-bit Editing now available in Photoshop Beta <https://community.adobe.com/t5/photoshop-beta-discussions/new-feature-opencolorio-and-32-bit-editing-now-available-in-photoshop-beta/td-p/14767506>`__.
 
 Photoshop

diff --git a/docs/index.rst b/docs/index.rst
@@ -43,7 +43,7 @@ Accessing Other Versions
 ************************
 
 You are reading the documentation for OCIO v2.  The documentation for the earlier
-1.x series of releases is available `here <https://opencolorio.org/old/index.html>`_.
+1.x series of releases is available `here <https://opencolorio.org/old/index.html>`__.
 
 
 Community
@@ -70,7 +70,7 @@ Slack
 
 There is an OpenColorIO Slack workspace at: `<https://opencolorio.slack.com>`_.  
 
-New users may join the workspace from `here <http://slack.opencolorio.org/>`_.
+New users may join the workspace from `here <http://slack.opencolorio.org/>`__.
 
 
 Search

diff --git a/docs/quick_start/installation.rst b/docs/quick_start/installation.rst
@@ -26,14 +26,14 @@ Python
 
 If you only need the Python binding and command-line tools, the simplest solution is to 
 take advantage of the pre-built wheels in the Python Package Index (PyPI) 
-`here <https://pypi.org/project/opencolorio>`_. It can be installed as follows, once you 
+`here <https://pypi.org/project/opencolorio>`__. It can be installed as follows, once you 
 have Python installed.
 
 **PyPI**::
 
     pip install opencolorio
 
-The pre-built wheels are listed `here <https://pypi.org/project/opencolorio/#files>`_.  Note that
+The pre-built wheels are listed `here <https://pypi.org/project/opencolorio/#files>`__.  Note that
 source code is provided, so it may be possible for ``pip`` to compile the binding on your machine if
 the matrix of Python version and platform version does not have the combination you need.  More
 detailed instructions are available for how to use 
@@ -88,7 +88,7 @@ If you need the extra command-line tools, you'll need to install :ref:`from sour
 However, the Python binding can be installed as described in the :ref:`Python` section.
 
 MacOS using Homebrew
-*******************
+********************
 
 You can use the Homebrew package manager to install OpenColorIO on macOS.
 
@@ -264,9 +264,7 @@ Enabling optional components
 CMake Options
 +++++++++++++
 
-There are many options available in `CMake. 
-
-<https://cmake.org/cmake/help/latest/guide/user-interaction/index.html#guide:User%20Interaction%20Guide>`_
+There are many options available in `CMake. <https://cmake.org/cmake/help/latest/guide/user-interaction/index.html#guide:User%20Interaction%20Guide>`_
 
 Several of the most common ones are:
 
@@ -531,7 +529,7 @@ Note: For other user facing environment variables, see :ref:`using_env_vars`.
     It is recommended to build OFX plugins in static mode 
     (``BUILD_SHARED_LIBS=OFF``) to avoid any issue loading the OpenColorIO
     library from the plugin once it has been moved. Otherwise, please make sure
-    the shared OpenColorIO lib (*.so, *.dll, *.dylib) is visible from the
+    the shared OpenColorIO lib (\*.so, \*.dll, \*.dylib) is visible from the
     plugin by mean of ``PATH``, ``LD_LIBRARY_PATH`` or ``DYLD_LIBRARY_PATH``
     for Windows, Linux and macOS respectively. For systems that supports it,
     it is also possible to edit the RPATH of the plugin to add the location of

diff --git a/docs/toc_redirect.rst b/docs/toc_redirect.rst
@@ -40,4 +40,4 @@
 .. toctree::
    :hidden:
 
-   aswf/_index
+   aswf/_index