Merge branch 'release' into fix-core-profile

Author: brechtvl

BUILDING.md

@@ -118,10 +118,15 @@ that depend on Metal, including:
 
 ##### Vulkan
 
+Vulkan support for USD is currently experimental and disabled by default.
+
 Building USD with Vulkan enabled requires the Vulkan SDK and glslang to
-be installed. The VULKAN_SDK environment variable must point to the
-location of the SDK. The glslang compiler headers must be locatable during
-the build process.
+be installed. If you wish to build a debug build on Windows, please make sure 
+you have the optional component "Shader Toolchain Debug Symbols" installed as 
+part of the Vulkan SDK.
+
+The VULKAN_SDK environment variable must point to the location of the SDK. The 
+glslang compiler headers must be locatable during the build process.
 
 Support for Vulkan can optionally be enabled by specifying the cmake flag
 `PXR_ENABLE_VULKAN_SUPPORT=TRUE`.
@@ -157,23 +162,45 @@ parse metadata from OSL shaders.
 Doxygen documentation can optionally be generated by specifying the cmake flag
 `PXR_BUILD_DOCUMENTATION=TRUE`.
 
-The additional dependencies that must be supplied for enabling documentation 
+There are two documentation sub-components, controlled by setting
+`PXR_BUILD_HTML_DOCUMENTATION` and `PXR_BUILD_PYTHON_DOCUMENTATION`. See the
+sections below for descriptions of precisely what they control.  Neither sub-
+component will have any effect if `PXR_BUILD_DOCUMENTATION` is not `TRUE`.
+
+The additional dependencies that must be supplied for enabling documentation
 generation are:
 
 | Dependency Name    | Description                             |
-| ------------------ |---------------------------------------  | 
+| ------------------ |---------------------------------------  |
 | DOXYGEN_EXECUTABLE | The location of Doxygen                 |
+
+See [3rd Party Library and Application Versions](VERSIONS.md) for version
+information, including supported Doxygen versions.
+
+##### HTML Documentation
+
+If `PXR_BUILD_HTML_DOCUMENTATION` evaluates `TRUE` then building of the HTML
+documentation is enabled.  This includes USD overview and general concepts, and
+the C++ API documentation.  It defaults to `TRUE`, and so is built by default
+when `PXR_BUILD_DOCUMENTATION` is also enabled (but has no effect if
+`PXR_BUILD_DOCUMENTATION` is not set.)
+
+The additional dependencies that must be supplied for enabling HTML
+documentation generation are:
+
+| Dependency Name    | Description                             |
+| ------------------ |---------------------------------------  |
 | DOT_EXECUTABLE     | The location of Dot(from GraphViz).     |
 
-See [3rd Party Library and Application Versions](VERSIONS.md) for version 
-information, including supported Doxygen and GraphViz versions.
+See [3rd Party Library and Application Versions](VERSIONS.md) for version
+information, including supported 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. 
+enabled. It defaults to `FALSE`.
 
 This process uses the scripts in the docs/python subdirectory. Relevant
 documentation from generated doxygen XML data is extracted and matched with