Generating Python API docs

.gitignore

@@ -1,2 +1,3 @@
 build
+documents/PythonAPI/sources/generated/
 dist

CMakeLists.txt

@@ -33,10 +33,15 @@ endif()
 
 project(MaterialX VERSION ${MATERIALX_LIBRARY_VERSION})
 
+# Build options
 option(MATERIALX_BUILD_PYTHON "Build the MaterialX Python package from C++ bindings. Requires Python 3.6 or greater." OFF)
 option(MATERIALX_BUILD_VIEWER "Build the MaterialX Viewer." OFF)
 option(MATERIALX_BUILD_GRAPH_EDITOR "Build the MaterialX Graph Editor." OFF)
 option(MATERIALX_BUILD_DOCS "Create HTML documentation using Doxygen. Requires that Doxygen be installed." OFF)
+option(MATERIALX_BUILD_PYTHON_DOCS "Create HTML documentation for the MaterialX Python API using Sphinx. Requires that Sphinx be installed." OFF)
+if(MATERIALX_BUILD_PYTHON_DOCS)
+    set(MATERIALX_BUILD_PYTHON ON)
+endif()
 
 option(MATERIALX_BUILD_GEN_GLSL "Build the GLSL shader generator back-end." ON)
 option(MATERIALX_BUILD_GEN_OSL "Build the OSL shader generator back-end." ON)
@@ -158,6 +163,7 @@ message(STATUS "Setting namespace to '${MATERIALX_NAMESPACE}'")
 set (MATERIALX_LIBNAME_SUFFIX "" CACHE STRING "Specify a suffix to all libraries that are built")
 
 mark_as_advanced(MATERIALX_BUILD_DOCS)
+mark_as_advanced(MATERIALX_BUILD_PYTHON_DOCS)
 mark_as_advanced(MATERIALX_BUILD_GEN_GLSL)
 mark_as_advanced(MATERIALX_BUILD_GEN_OSL)
 mark_as_advanced(MATERIALX_BUILD_GEN_MDL)
@@ -507,6 +513,9 @@ endif()
 if(MATERIALX_BUILD_DOCS)
     add_subdirectory(documents)
 endif()
+if(MATERIALX_BUILD_PYTHON_DOCS)
+    add_subdirectory(documents/PythonAPI)
+endif()
 
 if(MATERIALX_BUILD_JS)
     add_subdirectory(source/JsMaterialX)

cmake/modules/FindSphinx.cmake

@@ -0,0 +1,18 @@
+include(FindPackageHandleStandardArgs)
+
+find_package(Python3)
+if(PYTHON3_FOUND)
+    get_filename_component(_PYTHON_EXECUTABLE_DIR "${PYTHON_EXECUTABLE}" DIRECTORY)
+    set(_SPHINX_SEARCH_PATHS
+        "${_PYTHON_EXECUTABLE_DIR}"
+        "${_PYTHON_EXECUTABLE_DIR}/bin"
+        "${_PYTHON_EXECUTABLE_DIR}/Scripts"
+        "${_PYTHON_EXECUTABLE_DIR}/../opt/sphinx-doc/bin")
+    message(STATUS "Looking for Sphinx in the following directories: ${_SPHINX_SEARCH_PATHS}")
+    find_program(SPHINX_EXECUTABLE
+                 NAMES sphinx-build sphinx-build.exe
+                 HINTS ${_SPHINX_SEARCH_PATHS})
+    mark_as_advanced(SPHINX_EXECUTABLE)
+
+    find_package_handle_standard_args(Sphinx DEFAULT_MSG SPHINX_EXECUTABLE)
+endif()

documents/DeveloperGuide/MainPage.md

@@ -52,6 +52,8 @@ Select the `MATERIALX_BUILD_VIEWER` option to build the MaterialX Viewer.  Insta
 
 To generate HTML documentation for the MaterialX C++ API, make sure a version of [Doxygen](https://www.doxygen.org/) is on your path, and select the advanced option `MATERIALX_BUILD_DOCS` in CMake.  This option will add a target named `MaterialXDocs` to your project, which can be built as an independent step from your development environment.
 
+To generate HTML documentation for the MaterialX Python API, make sure a version of [Sphinx](https://www.sphinx-doc.org/) is on your path, and select the advanced option `MATERIALX_BUILD_PYTHON_DOCS` in CMake.  This option will add a target named `MaterialXDocsPython` to your project, which can be built as an independent step from your development environment.
+
 ## Installing MaterialX
 
 Building the `install` target of your project will install the MaterialX C++ and Python libraries to the folder specified by the `CMAKE_INSTALL_PREFIX` setting, and will install MaterialX Python as a third-party library in your Python environment.  Installation of MaterialX Python as a third-party library can be disabled by setting `MATERIALX_INSTALL_PYTHON` to `OFF`.

documents/PythonAPI/CMakeLists.txt

@@ -0,0 +1,53 @@
+# Use `CMAKE_MODULE_PATH` to be able to find the Sphinx executables
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake/modules")
+
+find_package(Sphinx REQUIRED)
+
+set(SPHINX_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR})
+set(SPHINX_RST_SOURCE_DIR ${SPHINX_SOURCE_DIR}/sources)
+set(SPHINX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR})
+set(SPHINX_HTML_OUTPUT_DIR ${SPHINX_OUTPUT_DIR})
+set(MATERIALX_PYTHON_DOCS_TARGET_DEPENDENCIES
+    MaterialXCore
+    PyMaterialXCore
+    PyMaterialXFormat
+    PyMaterialXGenShader
+    PyMaterialXGenGlsl
+    PyMaterialXGenOsl
+    PyMaterialXGenMdl
+    PyMaterialXGenMsl
+    PyMaterialXRender
+    PyMaterialXRenderGlsl
+    PyMaterialXRenderOsl
+    PyMaterialXRenderMsl)
+
+# Generate the Sphinx configuration file `conf.py` from `conf.py.in`
+set(MATERIALX_PYTHONPATH ${CMAKE_BINARY_DIR}/lib)
+set(MATERIALX_LOGO_FILENAME "MaterialXLogo_200x155.png")
+configure_file(${SPHINX_SOURCE_DIR}/conf.py.in
+               ${SPHINX_OUTPUT_DIR}/conf.py)
+
+# Add a custom target to invoke `sphinx-build` to generate the Python API docs,
+# which depends on the Python bindings to be built
+add_custom_target(MaterialXDocsPython
+                  ${SPHINX_EXECUTABLE} --fresh-env --conf-dir ${SPHINX_OUTPUT_DIR}
+                  ${SPHINX_RST_SOURCE_DIR}
+                  ${SPHINX_HTML_OUTPUT_DIR}
+                  WORKING_DIRECTORY ${SPHINX_OUTPUT_DIR}
+                  DEPENDS ${MATERIALX_PYTHON_DOCS_TARGET_DEPENDENCIES}
+                  COMMENT "Building MaterialX Python API Documentation: ${SPHINX_HTML_OUTPUT_DIR}/index.html")
+
+# Add post-build commands to copy our logo and custom style sheet to the "_static" folder
+add_custom_command(TARGET MaterialXDocsPython
+                   POST_BUILD COMMAND
+                   ${CMAKE_COMMAND} -E copy
+                       ${SPHINX_SOURCE_DIR}/custom.css
+                       ${SPHINX_HTML_OUTPUT_DIR}/_static/custom.css)
+add_custom_command(TARGET MaterialXDocsPython
+                   POST_BUILD COMMAND
+                   ${CMAKE_COMMAND} -E copy
+                       ${CMAKE_SOURCE_DIR}/documents/Images/${MATERIALX_LOGO_FILENAME}
+                       ${SPHINX_HTML_OUTPUT_DIR}/_static/)
+
+install(DIRECTORY ${SPHINX_OUTPUT_DIR}
+        DESTINATION "documents/PythonAPI" MESSAGE_NEVER)