[docs] fixes for python docstring builds on windows

cmake/macros/Public.cmake

@@ -1284,6 +1284,11 @@ function(pxr_build_python_documentation)
     string(REPLACE ";" "," pxrPythonModulesStr "${pxrPythonModules}")
     # Run convertDoxygen on the module list, setting PYTHONPATH 
     # to the install path for the USD Python modules
+    if (WIN32)
+        set(DLL_PATH_FLAG "--dllPath \"${CMAKE_INSTALL_PREFIX}/lib;${CMAKE_INSTALL_PREFIX}/bin;${CMAKE_INSTALL_PREFIX}/plugin/usd;${CMAKE_INSTALL_PREFIX}/share/usd/examples/plugin\"")
+    else()
+        set(DLL_PATH_FLAG "")
+    endif()
     install(CODE "\
         execute_process(\
             WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/cmake \
@@ -1292,6 +1297,7 @@ function(pxr_build_python_documentation)
                 --package pxr --module ${pxrPythonModulesStr} \
                 --inputIndex ${BUILT_XML_DOCS}/index.xml \
                 --pythonPath ${CMAKE_INSTALL_PREFIX}/lib/python \
+                ${DLL_PATH_FLAG} \
                 --output ${INSTALL_PYTHON_PXR_ROOT})
         if (NOT \${convert_doxygen_return_code} EQUAL \"0\")
             message( FATAL_ERROR \"Error generating python docstrings - ${CONVERT_DOXYGEN_TO_PYTHON_DOCS_SCRIPT} return code: \${convert_doxygen_return_code} \")

docs/python/convertDoxygen.py

@@ -24,8 +24,8 @@
 #
 # convertDoxygen.py
 #
-# A utility to convert Doxygen XML files into another format, such as 
-# Python docstrings. 
+# A utility to convert Doxygen XML files into another format, such as
+# Python docstrings.
 #
 # This utility is designed to make it easy to plug in new output
 # formats. This is done by creating new cdWriterXXX.py modules. A
@@ -49,19 +49,25 @@
 output_file   = GetArgValue(['--output', '-o'])
 output_format = GetArgValue(['--format', '-f'], "Docstring")
 python_path = GetArgValue(['--pythonPath'])
+dll_path = GetArgValue(['--dllPath'])
 
 SetDebugMode(GetArg(['--debug', '-d']))
 
 if not (xml_file or xml_index_file) or not output_file or GetArg(['--help', '-h']):
     Usage()
 
 #
-# If caller specified an additional path for python libs (for loading USD 
+# If caller specified an additional path for python libs (for loading USD
 # modules, for example) add the path to sys.path
 #
 if (python_path != None):
     sys.path.append(python_path)
 
+if dll_path != None and os.name == "nt":
+    dll_paths = dll_path.replace("/", os.sep).split(";")
+    for path in dll_paths:
+        if os.path.isdir(path):
+            os.add_dll_directory(path)
 #
 # Try to import the plugin module that creates the desired output
 #
@@ -88,7 +94,7 @@
 
 #
 # Traverse the list of DocElements from the parsed XML,
-# load provided python module(s) and find matching python 
+# load provided python module(s) and find matching python
 # entities, and write matches to python docs output
 #
 packageName = GetArgValue(['--package', '-p'])
@@ -103,13 +109,13 @@
     # Processing multiple modules. Writer's constructor will verify
     # provided package and modules can be loaded
     moduleList = modules.split(",")
-    # Loop through module list and create a Writer for each module to 
+    # Loop through module list and create a Writer for each module to
     # load and generate the doc strings for the specific module
     for moduleName in moduleList:
         if not moduleName:
             continue
         writer = Writer(packageName, moduleName)
-        # Parser.traverse builds the docElement tree for all the 
+        # Parser.traverse builds the docElement tree for all the
         # doxygen XML files, so we only need to call it once if we're
         # processing multiple modules
         if (docList is None):

docs/python/doxygenlib/cdUtils.py

@@ -134,13 +134,16 @@ def Usage():
   --debug or -d   = turn on debugging mode
   --help or -h    = display this program usage statement
   --pythonPath    = optional path to add to python lib paths
+  --dllPath       = optional ;-separated paths to add to window's list of
+                    directories you may load .dll libraries from. Ignored if not
+                    on windows.
 
 Docstring format:
   Write Python doc strings from Doyxgen C++ comments. Writes
   output to file or directory as specified by --output option.
 
   --package or -p = the package name, e.g. pxr
-  --module or -m  = the module name, e.g. UsdGeom, or a list of 
+  --module or -m  = the module name, e.g. UsdGeom, or a list of
                     comma-separated modules, e.g. Usd,UsdGeom,UsdShade
     """ % (progname, progname)
     print(usageMsg)