Merge release v23.05

BUILDING.md

@@ -35,10 +35,7 @@ Some examples:
 ```bash
 cmake                                       \
 -DTBB_ROOT_DIR=/path/to/tbb                 \
--DOPENEXR_LOCATION=/path/to/openexr         \
 -DOPENSUBDIV_ROOT_DIR=/path/to/opensubdiv   \
--DPTEX_LOCATION=/path/to/ptex               \
--DOIIO_LOCATION=/path/to/openimageio        \
 -DBOOST_ROOT=/path/to/boost                 \
 /path/to/USD/source
 
@@ -53,10 +50,7 @@ The following will generate an Xcode project that can be used to build USD.
 cmake                                       \
 -G "Xcode"                                  \
 -DTBB_ROOT_DIR=/path/to/tbb                 \
--DOPENEXR_LOCATION=/path/to/openexr         \
 -DOPENSUBDIV_ROOT_DIR=/path/to/opensubdiv   \
--DPTEX_LOCATION=/path/to/ptex               \
--DOIIO_LOCATION=/path/to/openimageio        \
 -DBOOST_ROOT=/path/to/boost                 \
 /path/to/USD/source
 
@@ -65,24 +59,27 @@ cmake --build . --target install -- -j <NUM_CORES>
 
 #### On Windows
 
-The following will generate a Visual Studio 2015 solution that can be used to
+The following will generate a Visual Studio 2017 solution that can be used to
 build USD.
 
 ```cmd.exe
 "C:\Program Files\CMake\bin\cmake.exe"      ^
--G "Visual Studio 14 2015 Win64"            ^
+-G "Visual Studio 15 2017 Win64"            ^
 -DTBB_ROOT_DIR=C:\path\to\tbb               ^
--DOPENEXR_LOCATION=C:\path\to\openexr       ^
 -DOPENSUBDIV_ROOT_DIR=C:\path\to\opensubdiv ^
--DPTEX_LOCATION=C:\path\to\ptex             ^
--DOIIO_LOCATION=C:\path\to\openimageio      ^
 -DBOOST_ROOT=C:\path\to\boost               ^
 \path\to\USD\source
 
 cmake --build . --target install -- /m:%NUMBER_OF_PROCESSORS%
 ```
 
-Note: if you're trying to build with Visual Studio 2017, use the "Visual Studio 15 2017 Win64" generator.
+For other versions of Visual Studio, use the following cmake arguments:
+
+- For VS2019: `-G "Visual Studio 16 2019" -A x64`
+- For VS2022: `-G "Visual Studio 17 2022" -A x64`
+
+For more information on Visual Studio generators for cmake, see 
+[Visual Studio Generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators).
 
 ## Optional Components
 
@@ -92,18 +89,17 @@ removes the need for their dependencies when building USD.
 
 ##### Python
 
-Python support in USD refers to:
+Some optional USD components use Python:
 - [The USD Toolset](https://graphics.pixar.com/usd/docs/USD-Toolset.html)
 - [Third Party Plugins](https://graphics.pixar.com/usd/docs/USD-3rd-Party-Plugins.html)
 - Python language bindings for the USD C++ API
 - Unit tests using Python
 
+Please refer to [VERSIONS.md](VERSIONS.md) for supported Python versions.
+
 Support for Python can optionally be disabled by specifying the cmake flag
 `PXR_ENABLE_PYTHON_SUPPORT=FALSE`.
 
-Python 3 is enabled by default, Python 2 can be enabled by specifying the cmake
-flag `PXR_USE_PYTHON_3=OFF`.
-
 ##### OpenGL
 
 Support for OpenGL can optionally be disabled by specifying the cmake flag
@@ -130,6 +126,23 @@ the build process.
 Support for Vulkan can optionally be enabled by specifying the cmake flag
 `PXR_ENABLE_VULKAN_SUPPORT=TRUE`.
 
+##### MaterialX
+
+Enable [MaterialX](https://github.com/materialx/materialx) support in the 
+build by specifying the cmake flag `PXR_ENABLE_MATERIALX_SUPPORT=TRUE` when
+invoking cmake. Note that MaterialX with shared library support is required.
+
+When building via build_usd.py, MaterialX support is enabled by default. The
+default can be overriden using the --materialx and --no-materialx flags.
+
+The additional dependencies that must be supplied when invoking cmake are:
+
+| Dependency Name    | Description                                                 |
+| ------------------ |-----------------------------------------------------------  |
+| MaterialX_DIR      | Path to the CMake package config of a MaterialX SDK install.|
+
+See [3rd Party Library and Application Versions](VERSIONS.md) for version information.
+
 ##### OSL (OpenShadingLanguage)
 
 Support for OSL is disabled by default, and can optionally be enabled by
@@ -152,8 +165,22 @@ generation are:
 | DOXYGEN_EXECUTABLE | The location of Doxygen                 |
 | DOT_EXECUTABLE     | The location of Dot(from GraphViz).     |
 
-See [3rd Party Library and Application Versions](VERSIONS.md) for version information.
+See [3rd Party Library and Application Versions](VERSIONS.md) for version 
+information, including supported Doxygen and GraphViz versions.
+
+##### Python Documentation
+
+Python docstrings for Python entities can be generated by specifying the cmake
+flag `PXR_BUILD_PYTHON_DOCUMENTATION`. This process requires that Python support
+(`PXR_ENABLE_PYTHON_SUPPORT`) and documentation (`PXR_BUILD_DOCUMENTATION`) are
+enabled. 
 
+This process uses the scripts in the docs/python subdirectory. Relevant
+documentation from generated doxygen XML data is extracted and matched with
+associated Python classes, functions, and properties in the built Python 
+modules. A `__DOC.py` file is generated and installed in each of the directories 
+of the installed Python modules. The `__DOC.py` file adds the docstrings to the 
+Python entities when the module is loaded.
 
 ##### Imaging
 
@@ -163,10 +190,6 @@ Disable this component by specifying the cmake flag `PXR_BUILD_IMAGING=FALSE` wh
 invoking cmake. Disabling this component will also disable the [USD Imaging](#usd-imaging)
 component and any [Imaging Plugins](#imaging-plugins).
 
-Support for Ptex can optionally be disabled by specifying the cmake flag
-`PXR_ENABLE_PTEX_SUPPORT=FALSE`.
-
-
 ##### USD Imaging
 
 This component provides the USD imaging delegates for Hydra, as well as
@@ -176,10 +199,38 @@ Disable this component by specifying the cmake flag `PXR_BUILD_USD_IMAGING=FALSE
 invoking cmake. usdview may also be disabled independently by specifying the cmake flag 
 `PXR_BUILD_USDVIEW=FALSE`.
 
+##### Command-line Tools
+
+USD by default builds several helpful command-line tools for validating and 
+manipulating USD files. For more information on the tools, see [USD Toolset](https://graphics.pixar.com/usd/release/toolset.html).
+
+Disable building the command-line tools by specifying the cmake flag 
+`PXR_BUILD_USD_TOOLS=FALSE` when invoking cmake. 
+
+##### Examples
+
+USD by default builds several example projects that demonstrate how to develop
+various extensions and plugins.
+
+Disable building the examples by specifying the cmake flag 
+`PXR_BUILD_EXAMPLES=FALSE` when invoking cmake. 
+
+##### Tutorials
+
+USD by default builds USD and Python files used for the [USD Tutorials](https://graphics.pixar.com/usd/release/tut_usd_tutorials.html).
+
+Disable building the tutorial support files by specifying the cmake flag 
+`PXR_BUILD_TUTORIALS=FALSE` when invoking cmake. 
+
 ## Imaging Plugins
 
 Hydra's rendering functionality can be extended with these optional plugins.
 
+##### Ptex
+
+Support for Ptex is disabled by default and can be enabled by specifying the 
+cmake flag `PXR_ENABLE_PTEX_SUPPORT=TRUE`.
+
 ##### OpenImageIO 
 
 This plugin can optionally be enabled by specifying the cmake flag
@@ -268,20 +319,6 @@ support requires the following dependencies:
 
 For further information see the documentation on the Alembic plugin [here](http://openusd.org/docs/Alembic-USD-Plugin.html).
 
-##### MaterialX Plugin
-
-Enable [MaterialX](https://github.com/materialx/materialx) support in the 
-build by specifying the cmake flag `PXR_ENABLE_MATERIALX_SUPPORT=TRUE` when
-invoking cmake. Note that MaterialX with shared library support is required.
-
-The additional dependencies that must be supplied when invoking cmake are:
-
-| Dependency Name    | Description                                                 |
-| ------------------ |-----------------------------------------------------------  |
-| MaterialX_DIR      | Path to the CMake package config of a MaterialX SDK install.|
-
-See [3rd Party Library and Application Versions](VERSIONS.md) for version information.
-
 ##### Draco Plugin
 
 Enable the [Draco](https://github.com/google/draco) plugin in the build by specifying the cmake flag `PXR_BUILD_DRACO_PLUGIN=TRUE`