Add pybind11 docs (#2657)

## Purpose
- Add in Python docs into the MaterialX package for all modules
- This allows for standard Python help and the ability to integrate this with things like type stubs (pyi)
An example of this integrated into VSCode and PyCharm is shown
- Tooling used to create html docs via tools like Sphinx but does not add any reliance on such tools.

## Changes
- The existing build flag `MATERIALX_BUILD_DOCS` is used to:
  - Build docs with XML `Doxygen` output as extracted from C++ code.
  - Run a utility script to parse the XML to insert into PyMaterialX module files.
- The flag is enabled when building Python wheels.

Author: kwokcb

.github/workflows/main.yml

@@ -476,7 +476,9 @@ jobs:
         CIBW_SKIP: '*musllinux*'
         CIBW_ARCHS: 'auto64'
         CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
-        CIBW_BEFORE_ALL_LINUX: yum install -y libXt-devel
+        CIBW_BEFORE_ALL_LINUX: yum install -y libXt-devel doxygen
+        CIBW_BEFORE_ALL_MACOS: brew install doxygen
+        CIBW_BEFORE_ALL_WINDOWS: choco install doxygen.install -y
         CIBW_BUILD_VERBOSITY: 1
         CIBW_ENVIRONMENT: CMAKE_BUILD_PARALLEL_LEVEL=2
         MACOSX_DEPLOYMENT_TARGET: '11.0'

CMakeLists.txt

@@ -135,6 +135,7 @@ set(MATERIALX_PYTHON_EXECUTABLE "" CACHE FILEPATH
     "Python executable to be used in building the MaterialX Python package (e.g. 'C:/Python39/python.exe').")
 set(MATERIALX_PYTHON_PYBIND11_DIR "" CACHE PATH
     "Path to a folder containing the PyBind11 source to be used in building MaterialX Python.")
+option(MATERIALX_PYTHON_FORCE_REPLACE_DOCS "Force replace existing docstrings when generating Python binding documentation from Doxygen." OFF)
 
 # Settings to define installation layout
 set(MATERIALX_INSTALL_INCLUDE_PATH "include" CACHE STRING "Install header include path (e.g. 'inc', 'include').")
@@ -210,6 +211,7 @@ mark_as_advanced(MATERIALX_DYNAMIC_ANALYSIS)
 mark_as_advanced(MATERIALX_PYTHON_VERSION)
 mark_as_advanced(MATERIALX_PYTHON_EXECUTABLE)
 mark_as_advanced(MATERIALX_PYTHON_PYBIND11_DIR)
+mark_as_advanced(MATERIALX_PYTHON_FORCE_REPLACE_DOCS)
 mark_as_advanced(MATERIALX_OSL_BINARY_OSLC)
 mark_as_advanced(MATERIALX_OSL_BINARY_TESTRENDER)
 mark_as_advanced(MATERIALX_OSL_INCLUDE_PATH)
@@ -548,16 +550,16 @@ if(MATERIALX_BUILD_TESTS)
     add_subdirectory(source/MaterialXTest)
 endif()
 
+if (MATERIALX_BUILD_DOCS)
+    add_subdirectory(documents)
+endif()
+
 # Add Python subdirectories
 if(MATERIALX_BUILD_PYTHON)
     add_subdirectory(source/PyMaterialX)
     add_subdirectory(python)
 endif()
 
-if(MATERIALX_BUILD_DOCS)
-    add_subdirectory(documents)
-endif()
-
 if(MATERIALX_BUILD_JS)
     add_subdirectory(source/JsMaterialX)
 endif()

documents/Doxyfile.in

@@ -23,3 +23,6 @@ FULL_SIDEBAR           = NO
 
 QUIET                  = YES
 WARN_IF_UNDOCUMENTED   = NO
+
+GENERATE_XML = YES
+XML_OUTPUT = doxygen_xml

pyproject.toml

@@ -56,17 +56,25 @@ logging.level = "DEBUG"
 # where the package is.
 wheel.packages = ["python/MaterialX"]
 
+sdist.include = [
+    "/documents",
+]
+
 sdist.exclude = [
     "/build",
     "/dist",
     "/resources",
     "/javascript",
-    "/documents",
     "/.github",
     "MANIFEST.in",
     "/source/JsMaterialX",
 ]
 
+wheel.exclude = [
+    "/documents",
+    "documents/",
+]
+
 [tool.scikit-build.metadata.version]
 # https://scikit-build-core.readthedocs.io/en/latest/configuration.html#dynamic-metadata
 provider = "scikit_build_core.metadata.regex"
@@ -81,6 +89,8 @@ result = "{major}.{minor}.{build}"
 [tool.scikit-build.cmake.define]
 MATERIALX_BUILD_SHARED_LIBS = 'OFF' # Be explicit
 MATERIALX_BUILD_PYTHON = 'ON'
+MATERIALX_BUILD_DOCS = 'ON'
+MATERIALX_PYTHON_FORCE_REPLACE_DOCS = 'ON'
 MATERIALX_TEST_RENDER = 'OFF'
 MATERIALX_WARNINGS_AS_ERRORS = 'ON'
 MATERIALX_BUILD_TESTS = 'OFF'