AcademySoftwareFoundation · StefanHabel · Oct 13, 2023 · Oct 18, 2023 · Oct 18, 2023 · Oct 18, 2023
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -13,6 +13,7 @@ enable_testing()
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_BINARY_DIR}/cmake/modules")
 
 # JavaScript setup 
 option(MATERIALX_BUILD_JS "Build the MaterialX JavaScript package from C++ bindings. Requires the emscripten environment." OFF)
@@ -37,6 +38,10 @@ option(MATERIALX_BUILD_PYTHON "Build the MaterialX Python package from C++ bindi
 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 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)
@@ -125,6 +130,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)
@@ -331,7 +337,7 @@ if(MATERIALX_BUILD_PYTHON)
     add_subdirectory(python)
 endif()
 
-if(MATERIALX_BUILD_DOCS)
+if(MATERIALX_BUILD_DOCS OR MATERIALX_BUILD_PYTHON_DOCS)
     add_subdirectory(documents)
 endif()
 

diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="documents/Images/MaterialXLogo.png" height="170" />
+  <img src="https://raw.githubusercontent.com/AcademySoftwareFoundation/MaterialX/main/documents/Images/MaterialXLogo.png" height="170" />
 </p>
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/AcademySoftwareFoundation/MaterialX/blob/main/LICENSE)
@@ -32,29 +32,29 @@ The Python bindings for MaterialX are based on [PyBind11](https://github.com/pyb
 
 The [MaterialX Viewer](documents/DeveloperGuide/Viewer.md) leverages shader generation to build GLSL shaders from MaterialX graphs, rendering the results using the NanoGUI framework.
 
+Marble | Copper | Plastic | Carpaint
+-------|--------|---------|---------
+![MaterialX Marble material](https://raw.githubusercontent.com/AcademySoftwareFoundation/MaterialX/main/documents/Images/MaterialXView_Marble.png) | ![MaterialX Copper material](https://raw.githubusercontent.com/AcademySoftwareFoundation/MaterialX/main/documents/Images/MaterialXView_Copper.png) | ![MaterialX Plastic material](https://raw.githubusercontent.com/AcademySoftwareFoundation/MaterialX/main/documents/Images/MaterialXView_Plastic.png) | ![MaterialX Carpaint material](https://raw.githubusercontent.com/AcademySoftwareFoundation/MaterialX/main/documents/Images/MaterialXView_Carpaint.png) |
+
 **Figure 1:** Procedural and uniform materials in the MaterialX viewer
-<p float="left">
-  <img src="documents/Images/MaterialXView_Marble.png" width="204" />
-  <img src="documents/Images/MaterialXView_Copper.png" width="204" /> 
-  <img src="documents/Images/MaterialXView_Plastic.png" width="204" /> 
-  <img src="documents/Images/MaterialXView_Carpaint.png" width="204" /> 
-</p>
+
+Tiled Brass | Tiled Wood
+------------|-----------
+![MaterialX TiledBrass material](https://raw.githubusercontent.com/AcademySoftwareFoundation/MaterialX/main/documents/Images/MaterialXView_TiledBrass.png) | ![MaterialX TiledWood material](https://raw.githubusercontent.com/AcademySoftwareFoundation/MaterialX/main/documents/Images/MaterialXView_TiledWood.png)
 
 **Figure 2:** Textured, color-space-managed materials in the MaterialX viewer
-<p float="left">
-  <img src="documents/Images/MaterialXView_TiledBrass.png" width="412" />
-  <img src="documents/Images/MaterialXView_TiledWood.png" width="412" /> 
-</p>
 
 ### Open Chess Set
 
 The Open Chess Set is an open reference asset, consisting of a [MaterialX file](resources/Materials/Examples/StandardSurface/standard_surface_chess_set.mtlx) in the Standard Surface shading model and a [geometry file](resources/Geometry) in the glTF format.  It was authored by Moeen Sayed and Mujtaba Sayed, and was contributed to the MaterialX project by Side Effects.
 
+![The Open Chess Set rendered in Arnold for Maya](https://raw.githubusercontent.com/AcademySoftwareFoundation/MaterialX/main/documents/Images/OpenChessSet_Arnold_01.png)
+
 **Figure 3:** The Open Chess Set, rendered in Arnold for Maya
-<img src="documents/Images/OpenChessSet_Arnold_01.png" />
+
+![The Open Chess Set rendered in Karma XPU for Houdini](https://raw.githubusercontent.com/AcademySoftwareFoundation/MaterialX/main/documents/Images/OpenChessSet_Karma_01.png)
 
 **Figure 4:** The Open Chess Set, rendered in Karma XPU for Houdini
-<img src="documents/Images/OpenChessSet_Karma_01.png" />
 
 ### Pre-Built Binaries
 

diff --git a/cmake/modules/FindSphinx.cmake b/cmake/modules/FindSphinx.cmake
@@ -0,0 +1,20 @@
+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"
+    )
+
+    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()
diff --git a/documents/CMakeLists.txt b/documents/CMakeLists.txt
@@ -1,34 +1,114 @@
-set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR})
-set(DOXYGEN_HTML_OUTPUT_DIR ${DOXYGEN_OUTPUT_DIR}/html)
-set(DOXYGEN_INPUT_LIST ${CMAKE_SOURCE_DIR}/documents/DeveloperGuide/MainPage.md
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXCore
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXFormat
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenShader
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenShader/Nodes
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenGlsl
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenGlsl/Nodes
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenOsl
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenMdl
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXRender
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXRenderHw
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXRenderGlsl
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXRenderOsl
-                       )
-string (REPLACE ";" " " DOXYGEN_INPUT_STR "${DOXYGEN_INPUT_LIST}")
+# MaterialX C++ API Documentation
+if(MATERIALX_BUILD_DOCS)
+    find_package(Doxygen)
+    if(DOXYGEN_FOUND)
+        set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR})
+        set(DOXYGEN_HTML_OUTPUT_DIR ${DOXYGEN_OUTPUT_DIR}/html)
+        set(
+            DOXYGEN_INPUT_LIST
+            ${CMAKE_SOURCE_DIR}/documents/DeveloperGuide/MainPage.md
+            ${CMAKE_SOURCE_DIR}/source/MaterialXCore
+            ${CMAKE_SOURCE_DIR}/source/MaterialXFormat
+            ${CMAKE_SOURCE_DIR}/source/MaterialXGenShader
+            ${CMAKE_SOURCE_DIR}/source/MaterialXGenShader/Nodes
+            ${CMAKE_SOURCE_DIR}/source/MaterialXGenGlsl
+            ${CMAKE_SOURCE_DIR}/source/MaterialXGenGlsl/Nodes
+            ${CMAKE_SOURCE_DIR}/source/MaterialXGenOsl
+            ${CMAKE_SOURCE_DIR}/source/MaterialXGenMdl
+            ${CMAKE_SOURCE_DIR}/source/MaterialXRender
+            ${CMAKE_SOURCE_DIR}/source/MaterialXRenderHw
+            ${CMAKE_SOURCE_DIR}/source/MaterialXRenderGlsl
+            ${CMAKE_SOURCE_DIR}/source/MaterialXRenderOsl
+        )
+        string (REPLACE ";" " " DOXYGEN_INPUT_STR "${DOXYGEN_INPUT_LIST}")
 
-find_package(Doxygen)
+        configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
+                       ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
 
-if(DOXYGEN_FOUND)
-    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
-    add_custom_target(MaterialXDocs ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
-                      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-                      COMMENT "Generating HTML documentation: ${DOXYGEN_HTML_OUTPUT_DIR}/index.html")
-    add_custom_command(TARGET MaterialXDocs PRE_BUILD
-                       COMMAND ${CMAKE_COMMAND} -E copy_directory
-                       ${CMAKE_SOURCE_DIR}/documents/DoxygenAwesome ${CMAKE_CURRENT_BINARY_DIR})
-    add_custom_command(TARGET MaterialXDocs PRE_BUILD
-                       COMMAND ${CMAKE_COMMAND} -E copy_directory
-                       ${CMAKE_SOURCE_DIR}/documents/Images ${CMAKE_CURRENT_BINARY_DIR})
-    install(DIRECTORY ${DOXYGEN_HTML_OUTPUT_DIR}
-            DESTINATION "documents" MESSAGE_NEVER)
-endif(DOXYGEN_FOUND)
+        add_custom_target(
+            MaterialXDocs
+            ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+            WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+            COMMENT "Building MaterialX C++ API Documentation: ${DOXYGEN_HTML_OUTPUT_DIR}/index.html"
+        )
+        add_custom_command(
+            TARGET MaterialXDocs PRE_BUILD
+            COMMAND ${CMAKE_COMMAND}
+                -E copy_directory ${CMAKE_SOURCE_DIR}/documents/DoxygenAwesome
+                                  ${DOXYGEN_HTML_OUTPUT_DIR}
+        )
+        add_custom_command(
+            TARGET MaterialXDocs PRE_BUILD
+            COMMAND ${CMAKE_COMMAND}
+                -E copy_directory ${CMAKE_SOURCE_DIR}/documents/Images
+                                  ${DOXYGEN_HTML_OUTPUT_DIR}
+        )
+        install(DIRECTORY ${DOXYGEN_HTML_OUTPUT_DIR}
+                DESTINATION "documents"
+                MESSAGE_NEVER)
+    else()
+        message(WARNING "Unable to build MaterialX C++ API Documentation: Doxygen not found.")
+    endif(DOXYGEN_FOUND)
+endif(MATERIALX_BUILD_DOCS)
+
+
+# MaterialX Python API Documentation
+if(MATERIALX_BUILD_PYTHON_DOCS)
+    find_package(Sphinx)
+    if(SPHINX_FOUND)
+        set(SPHINX_SOURCE_DIR ${CMAKE_SOURCE_DIR}/documents/DeveloperGuide/)
+        set(SPHINX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR})
+        set(SPHINX_HTML_OUTPUT_DIR ${SPHINX_OUTPUT_DIR}/html-sphinx)
+        set(
+            MATERIALX_PYTHON_DOCS_TARGET_DEPENDENCIES
+            MaterialXCore
+            PyMaterialXCore
+            PyMaterialXFormat
+            PyMaterialXGenShader
+            PyMaterialXGenGlsl
+            PyMaterialXGenOsl
+            PyMaterialXGenMdl
+            PyMaterialXGenMsl
+            PyMaterialXRender
+            PyMaterialXRenderGlsl
+            PyMaterialXRenderOsl
+            PyMaterialXRenderMsl
+        )
+
+        # Configure the Sphinx configuration file `conf.py`
+        set(MATERIALX_PYTHONPATH ${CMAKE_SOURCE_DIR}/lib)
+        set(MATERIALX_LOGO_FILENAME "MaterialXLogo_200x155.png")
+        configure_file(${CMAKE_CURRENT_SOURCE_DIR}/sphinx-conf.py.in
+                       ${CMAKE_CURRENT_BINARY_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}
+                -c ${CMAKE_CURRENT_BINARY_DIR}
+                ${SPHINX_SOURCE_DIR}
+                ${SPHINX_HTML_OUTPUT_DIR}
+            WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_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 ${CMAKE_SOURCE_DIR}/documents/sphinx-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/
+        )
+    else()
+        message(WARNING "Unable to build MaterialX Python API Documentation: Sphinx not found.")
+    endif(SPHINX_FOUND)
+endif(MATERIALX_BUILD_PYTHON_DOCS)
diff --git a/documents/DeveloperGuide/GraphEditor.md b/documents/DeveloperGuide/GraphEditor.md
@@ -2,29 +2,30 @@
 
 The MaterialX Graph Editor is an example application for visualizing, creating, and editing MaterialX graphs.  It utilizes the ImGui framework as well as additional ImGui extensions such as the Node Editor.
 
-### Example Images
+## Example Images
+
+![MaterialX Graph Editor with procedural marble example](../Images/MaterialXGraphEditor_Marble.png)
 
 **Figure 1:** MaterialX Graph Editor with procedural marble example
-<img src="/documents/Images/MaterialXGraphEditor_Marble.png" />
 
-## Building The MaterialX Graph Editor
+## Building the MaterialX Graph Editor
 Select the `MATERIALX_BUILD_GRAPH_EDITOR` option in CMake to build the MaterialX Graph Editor.  Installation will copy the **MaterialXGraphEditor** executable to a `/bin` directory within the selected install folder.
 
-### Summary of Graph Editor Features
+## Summary of Graph Editor Features
 
 1.  **Load Material**: Load a material document in the MTLX format.
 2.  **Save Material**: Save out a graph as a mterial document in MTLX format.
 3.  **New Material**: Clear all information to set up for the creation of a new material
 4.  **Node Property Editor**: View or edit properties of the selected node.
 5.  **Render View**: View the rendered material.
 
-### Buttons
+## Buttons
 
-To display a new material and graph, click the `Load Material` button and and navigate to the [Example Materials](../../resources/Materials/Examples) folder, which contains a selection of materials in the MTLX format, and select a document to load.  The Graph Editor will display the graph hierarchy of the selected document for visualization and editing.
+To display a new material and graph, click the `Load Material` button and and navigate to the [Example Materials](https://github.com/AcademySoftwareFoundation/MaterialX/tree/main/resources/Materials/Examples) folder, which contains a selection of materials in the MTLX format, and select a document to load.  The Graph Editor will display the graph hierarchy of the selected document for visualization and editing.
 
 To save out changes to the graphs as MTLX files click the `Save Material` button.  This will save the position of the nodes in the graph for future use as well. 
 
-### Editor Window
+## Editor Window
 
 The MaterialX document is displayed as nodes in the Editor window.  When a file is intially loaded the material node, surface shader node, and any enclosing nodegraphs will be displayed.  Double-clicking on a nodegraph, or any node defined as a subgraph, will display the contents of that graph.
 
@@ -40,19 +41,19 @@ Another type of node present in the `Add Node` pop-up is the group, or backgroun
 
 To search the editor window for a specific node use `CTRL` + `F` to bring up the search bar. 
 
-### Node Property Editor
+## Node Property Editor
 When a node is selected in the graph, its information is displayed on the left-hand column in the `Node Property Editor`.  This editor displays the name of the node, its category, its inputs, the input name, types and values.  Inputs that are connected to other nodes will not display a value.
 
 This is where a node's properties such as its name and input values can be adjusted.  When an input value is changed the material is automatically updated to reflect that change.  The node info button displays the `doc` string for the selected node and its inputs if they exist. This `doc` string is currently read only.
 
 The show All Inputs checkbox displays all possible inputs for a node. With the box unchecked only inputs that have a connection or have had a value set will be shown. Only these inputs will be saved out when the graph is saved. 
 
-### Render View
+## Render View
 Above the `Node Property Editor`, the `Render View` displays the current material on the Arnold Shader Ball.  If inside a subgraph it will display the material associated with that subgraph; otherwise it will display the output of the selected node.  It automatically updates when any changes are made to the graph.
 
 To adjust the relative sizes of the Node Property Editor and Render View windows, drag the separator between these windows in the application. The render view window camera can be changed using the left or right mouse buttons to manipulate the shader ball. 
 
-### Keyboard Shortcuts
+## Keyboard Shortcuts
 
 - `TAB`: Add Node Popup
 - `Right Click`: pan along the editor
@@ -66,7 +67,7 @@ To adjust the relative sizes of the Node Property Editor and Render View windows
 - `+` : Zoom in with the camera when mouse is over the Render View Window.
 - `-` : Zoom out with the camera when mouse is over the Render View Window.
 
-### Command-Line Options
+## Command-Line Options
 
 The following are common command-line options for MaterialXGraphEditor, and a complete list can be displayed with the `--help` option.
 - `--material [FILENAME]` : Specify the filename of the MTLX document to be displayed in the graph editor
@@ -75,7 +76,7 @@ The following are common command-line options for MaterialXGraphEditor, and a co
 - `--library [FILEPATH]` : Specify an additional data library folder (e.g. 'vendorlib', 'studiolib').  This relative path will be appended to each location in the data search path when loading data libraries.
 - `--captureFilename [FILENAME]` : Specify the filename to which the first rendered frame should be written
 
-### Known Limitations
+## Known Limitations
 
 - Creating new connections using the `channels` attribute of an input is not yet supported, though existing `channels` connections will be displayed in graphs.
 - Assigning a new `colorspace` attribute to an input is not yet supported, though existing `colorspace` attributes on inputs will be respected by the render view.