[docs] allow building of python docstrings without generating HTML docs

For those interested in only the python docstrings, this speeds up the
build, and reduces the number of necessary extra dependencies (ie, graphviz
/ dot are no longer required to build python docstrings).

Doxygen is still needed to generate python docstrings, however, as the xml
generation is required.

The interface for `build_usd.py` is mostly unchanged, except that
`--build-docs` and `--build-python-docs` are now independent of each
other - ie, you can now specify `--build-python-docs` without
`--build-docs`, which will generate just the python docstrings and no
html.

At the cmake level, there are now 3 options:

- `PXR_BUILD_DOCUMENTATION`
- `PXR_BUILD_HTML_DOCUMENTATION` (new)
- `PXR_BUILD_PYTHON_DOCUMENTATION`

Both `PXR_BUILD_HTML_DOCUMENTATION` and
`PXR_BUILD_PYTHON_DOCUMENTATION` will only have an effect if
`PXR_BUILD_DOCUMENTATION` set.  Setting either of the `build_usd.py`
documentation flags (`--build-docs` and `--build-python-docs`) will turn
on `PXR_BUILD_DOCUMENTATION`, as well as their own sub-flag.

Both the `build_usd.py` and cmake interfaces are backwards compatible, in
the sense that non-erroring combinations of flags/options will still
continue to have the same result as previously.

BUILDING.md

@@ -157,23 +157,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

CMakeLists.txt

@@ -62,13 +62,13 @@ endif()
 
 if (PXR_BUILD_DOCUMENTATION)
     pxr_build_documentation()
-endif()   
 
-# If building python doc strings, run script
-# that uses doxygen build results and installed
-# USD python modules
-if (PXR_BUILD_PYTHON_DOCUMENTATION)
-    pxr_build_python_documentation()
-endif()
+    # If building python doc strings, run script
+    # that uses doxygen build results and installed
+    # USD python modules
+    if (PXR_BUILD_PYTHON_DOCUMENTATION)
+        pxr_build_python_documentation()
+    endif()
+endif()   
 
 pxr_toplevel_epilogue()

build_scripts/build_usd.py

@@ -1672,7 +1672,17 @@ def InstallUSD(context, force, buildArgs):
             extraArgs.append('-DPXR_BUILD_DOCUMENTATION=ON')
         else:
             extraArgs.append('-DPXR_BUILD_DOCUMENTATION=OFF')
-
+
+        if context.buildHtmlDocs:
+            extraArgs.append('-DPXR_BUILD_HTML_DOCUMENTATION=ON')
+        else:
+            extraArgs.append('-DPXR_BUILD_HTML_DOCUMENTATION=OFF')
+
+        if context.buildPythonDocs:
+            extraArgs.append('-DPXR_BUILD_PYTHON_DOCUMENTATION=ON')
+        else:
+            extraArgs.append('-DPXR_BUILD_PYTHON_DOCUMENTATION=OFF')
+
         if context.buildTests:
             extraArgs.append('-DPXR_BUILD_TESTS=ON')
         else:
@@ -1768,11 +1778,6 @@ def InstallUSD(context, force, buildArgs):
         else:
             extraArgs.append('-DPXR_ENABLE_MATERIALX_SUPPORT=OFF')
 
-        if context.buildPythonDocs:
-            extraArgs.append('-DPXR_BUILD_PYTHON_DOCUMENTATION=ON')
-        else:
-            extraArgs.append('-DPXR_BUILD_PYTHON_DOCUMENTATION=OFF')
-
         if Windows():
             # Increase the precompiled header buffer limit.
             extraArgs.append('-DCMAKE_CXX_FLAGS="/Zm150"')
@@ -1966,9 +1971,9 @@ def InstallUSD(context, force, buildArgs):
                       help="Do not build USD tools")
 subgroup = group.add_mutually_exclusive_group()
 subgroup.add_argument("--docs", dest="build_docs", action="store_true",
-                      default=False, help="Build documentation")
+                      default=False, help="Build overview and C++ documentation")
 subgroup.add_argument("--no-docs", dest="build_docs", action="store_false",
-                      help="Do not build documentation (default)")
+                      help="Do not build overview and C++ documentation (default)")
 subgroup = group.add_mutually_exclusive_group()
 subgroup.add_argument("--python-docs", dest="build_python_docs", action="store_true",
                       default=False, help="Build Python docs")
@@ -2195,12 +2200,16 @@ def __init__(self, args):
 
         # Optional components
         self.buildTests = args.build_tests
-        self.buildDocs = args.build_docs
         self.buildPython = args.build_python
         self.buildExamples = args.build_examples
         self.buildTutorials = args.build_tutorials
         self.buildTools = args.build_tools
 
+        # - Documentation
+        self.buildDocs = args.build_docs or args.build_python_docs
+        self.buildHtmlDocs = args.build_docs
+        self.buildPythonDocs = args.build_python_docs
+
         # - Imaging
         self.buildImaging = (args.build_imaging == IMAGING or
                              args.build_imaging == USD_IMAGING)
@@ -2236,9 +2245,6 @@ def __init__(self, args):
         # - MaterialX Plugin
         self.buildMaterialX = args.build_materialx
 
-        # - Python docs
-        self.buildPythonDocs = args.build_python_docs        
-
     def GetBuildArguments(self, dep):
         return self.buildArgs.get(dep.name.lower(), [])
 
@@ -2396,7 +2402,8 @@ def _JoinVersion(v):
     if not which("doxygen"):
         PrintError("doxygen not found -- please install it and adjust your PATH")
         sys.exit(1)
-
+
+if context.buildHtmlDocs:
     if not which("dot"):
         PrintError("dot not found -- please install graphviz and adjust your "
                    "PATH")

cmake/defaults/Packages.cmake

@@ -182,14 +182,16 @@ if (PXR_BUILD_DOCUMENTATION)
                 "doxygen not found, required for PXR_BUILD_DOCUMENTATION")
     endif()
 
-    find_program(DOT_EXECUTABLE
-        NAMES dot
-    )
-    if (EXISTS ${DOT_EXECUTABLE})
-        message(STATUS "Found dot: ${DOT_EXECUTABLE}") 
-    else()
-        message(FATAL_ERROR
-                "dot not found, required for PXR_BUILD_DOCUMENTATION")
+    if (PXR_BUILD_HTML_DOCUMENTATION)
+        find_program(DOT_EXECUTABLE
+            NAMES dot
+        )
+        if (EXISTS ${DOT_EXECUTABLE})
+            message(STATUS "Found dot: ${DOT_EXECUTABLE}") 
+        else()
+            message(FATAL_ERROR
+                    "dot not found, required for PXR_BUILD_DOCUMENTATION")
+        endif()
     endif()
 endif()
 

cmake/macros/Public.cmake

@@ -24,6 +24,14 @@
 include(Private)
 
 function(pxr_build_documentation)
+    # Cmake booleans are often, ie, "OFF", while Doxyfile requires booleans
+    # to be "YES" or "NO"
+    if(PXR_BUILD_HTML_DOCUMENTATION)
+        set(DOXYGEN_GENERATE_HTML "YES")
+    else()
+        set(DOXYGEN_GENERATE_HTML "NO")
+    endif()
+
     configure_file(${PROJECT_SOURCE_DIR}/docs/doxygen/Doxyfile.in
                    ${PROJECT_BINARY_DIR}/Doxyfile)
 
@@ -55,11 +63,13 @@ function(pxr_build_documentation)
         DESTINATION ${INST_DOCS_ROOT}
     )
 
-    set(BUILT_HTML_DOCS "${PROJECT_BINARY_DIR}/docs/doxy_html")
-    install(
-        DIRECTORY ${BUILT_HTML_DOCS}
-        DESTINATION ${INST_DOCS_ROOT}
-    )
+    if(PXR_BUILD_HTML_DOCUMENTATION)
+        set(BUILT_HTML_DOCS "${PROJECT_BINARY_DIR}/docs/doxy_html")
+        install(
+            DIRECTORY ${BUILT_HTML_DOCS}
+            DESTINATION ${INST_DOCS_ROOT}
+        )
+    endif()
 
     set(BUILT_XML_DOCS "${PROJECT_BINARY_DIR}/docs/doxy_xml")
     install(

docs/doxygen/Doxyfile.in

@@ -1047,7 +1047,7 @@ IGNORE_PREFIX          =
 # If the GENERATE_HTML tag is set to YES doxygen will generate HTML output
 # The default value is: YES.
 
-GENERATE_HTML          = YES
+GENERATE_HTML          = @DOXYGEN_GENERATE_HTML@
 
 # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -2091,7 +2091,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # set to NO
 # The default value is: NO.
 
-HAVE_DOT               = YES
+HAVE_DOT               = @DOXYGEN_GENERATE_HTML@
 
 # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
 # to run in parallel. When set to 0 doxygen will base this on the number of