From bef6e1fb478400d5a7a95c673a51f4a9d777c8d4 Mon Sep 17 00:00:00 2001 From: Stefan Habel <19556655+StefanHabel@users.noreply.github.com> Date: Thu, 12 Oct 2023 18:32:17 -0700 Subject: [PATCH] Update #342 Sphinx Python Documentation. Work in progress. This PR adds a new build target named `MaterialXDocsPython`, which generates Python API documentation using Sphinx. The existing developer guide contents are incorporated into the new HTML documentation, which lives side-by-side to the existing Doxygen-generated C++ API documentation. The docstrings of the Python modules were tweaked to describe what the individual modules are responsible for. Signed-off-by: Stefan Habel <19556655+StefanHabel@users.noreply.github.com> --- CMakeLists.txt | 1 + cmake/modules/FindSphinx.cmake | 20 ++ documents/CMakeLists.txt | 56 ++++- documents/DeveloperGuide/GraphEditor.md | 23 +- documents/DeveloperGuide/MainPage.md | 22 +- documents/DeveloperGuide/ShaderGeneration.md | 10 +- documents/DeveloperGuide/Viewer.md | 34 ++- documents/DeveloperGuide/index.rst | 53 +++++ documents/Doxyfile.in | 8 +- documents/sphinx-conf.py.in | 77 +++++++ documents/sphinx-custom.css | 207 ++++++++++++++++++ .../PyMaterialX/PyMaterialXCore/PyModule.cpp | 2 +- .../PyMaterialXFormat/PyModule.cpp | 2 +- .../PyMaterialXGenGlsl/PyModule.cpp | 2 +- .../PyMaterialXGenMdl/PyModule.cpp | 2 +- .../PyMaterialXGenMsl/PyModule.cpp | 2 +- .../PyMaterialXGenOsl/PyModule.cpp | 2 +- .../PyMaterialXGenShader/PyModule.cpp | 2 +- .../PyMaterialXRender/PyModule.cpp | 2 +- .../PyMaterialXRenderGlsl/PyModule.cpp | 2 +- .../PyMaterialXRenderMsl/PyModule.mm | 2 +- .../PyMaterialXRenderOsl/PyModule.cpp | 2 +- 22 files changed, 470 insertions(+), 63 deletions(-) create mode 100644 cmake/modules/FindSphinx.cmake create mode 100644 documents/DeveloperGuide/index.rst create mode 100644 documents/sphinx-conf.py.in create mode 100644 documents/sphinx-custom.css diff --git a/CMakeLists.txt b/CMakeLists.txt index de6aa7442f..a98d29579b 100644 --- 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) diff --git a/cmake/modules/FindSphinx.cmake b/cmake/modules/FindSphinx.cmake new file mode 100644 index 0000000000..24864cef35 --- /dev/null +++ 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" + ) +endif() + +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) diff --git a/documents/CMakeLists.txt b/documents/CMakeLists.txt index 56d2289b99..897708d17d 100644 --- a/documents/CMakeLists.txt +++ b/documents/CMakeLists.txt @@ -1,3 +1,4 @@ +# MaterialX C++ API Documentation 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 @@ -22,13 +23,62 @@ 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") + 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 ${CMAKE_CURRENT_BINARY_DIR}) + ${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 ${CMAKE_CURRENT_BINARY_DIR}) + ${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) + + +# MaterialX Python API Documentation +set(SPHINX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}) +set(SPHINX_HTML_OUTPUT_DIR ${SPHINX_OUTPUT_DIR}/html-sphinx) +set( + SPHINX_INPUT_LIST + ${CMAKE_SOURCE_DIR}/documents/DeveloperGuide/ +) +set(MATERIALX_PYTHONPATH ${CMAKE_SOURCE_DIR}/lib) +set(MATERIALX_LOGO_FILENAME "MaterialXLogo_200x155.png") + +find_package(Sphinx) + +if(SPHINX_FOUND) + configure_file(${CMAKE_CURRENT_SOURCE_DIR}/sphinx-conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/conf.py) + + add_custom_target(MaterialXDocsPython ${SPHINX_EXECUTABLE} + -c ${CMAKE_CURRENT_BINARY_DIR} + ${SPHINX_INPUT_LIST} + ${SPHINX_HTML_OUTPUT_DIR} + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + 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/ + ) + + # Add a post-build command to copy the DoxygenAwesome style sheet to the + # "_static" folder + add_custom_command( + TARGET MaterialXDocsPython POST_BUILD COMMAND ${CMAKE_COMMAND} + -E copy_directory ${CMAKE_SOURCE_DIR}/documents/DoxygenAwesome + ${SPHINX_HTML_OUTPUT_DIR}/_static/DoxygenAwesome + ) +else() + message(WARNING "Unable to build MaterialX Python API Documentation: Sphinx not found.") +endif(SPHINX_FOUND) diff --git a/documents/DeveloperGuide/GraphEditor.md b/documents/DeveloperGuide/GraphEditor.md index aaac7b75a2..a3444476c0 100644 --- a/documents/DeveloperGuide/GraphEditor.md +++ b/documents/DeveloperGuide/GraphEditor.md @@ -2,15 +2,16 @@ 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 - -## 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. @@ -18,13 +19,13 @@ Select the `MATERIALX_BUILD_GRAPH_EDITOR` option in CMake to build the MaterialX 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 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. diff --git a/documents/DeveloperGuide/MainPage.md b/documents/DeveloperGuide/MainPage.md index d6c098a23d..a35ee47b86 100644 --- a/documents/DeveloperGuide/MainPage.md +++ b/documents/DeveloperGuide/MainPage.md @@ -2,14 +2,14 @@ MaterialX is an open standard for representing rich material and look-development content in computer graphics, enabling its platform-independent description and exchange across applications and renderers. Launched at [Industrial Light & Magic](https://www.ilm.com/) in 2012, MaterialX has been a key technology in their feature films and real-time experiences since _Star Wars: The Force Awakens_ and _Millennium Falcon: Smugglers Run_. The project was released as open source in 2017, with companies including Sony Pictures Imageworks, Pixar, Autodesk, Adobe, and SideFX contributing to its ongoing development. In 2021, MaterialX became the seventh hosted project of the [Academy Software Foundation](https://www.aswf.io/). -### Quick Start for Developers +## Quick Start for Developers - Download the latest version of the [CMake](https://cmake.org/) build system. - Point CMake to the root of the MaterialX library and generate C++ projects for your platform and compiler. - Select the `MATERIALX_BUILD_PYTHON` option to build Python bindings. - Select the `MATERIALX_BUILD_VIEWER` option to build the MaterialX viewer. -### Supported Platforms +## Supported Platforms The MaterialX codebase requires a compiler with support for C++14, and can be built with any of the following: @@ -19,9 +19,9 @@ The MaterialX codebase requires a compiler with support for C++14, and can be bu The Python bindings for MaterialX are based on [PyBind11](https://github.com/pybind/pybind11), and support Python versions 3.6 and greater. -### Building MaterialX +## Building MaterialX -#### Building MaterialX C++ +### Building MaterialX C++ The MaterialX C++ libraries are automatically included when building MaterialX through CMake. @@ -32,7 +32,7 @@ To enable OpenImageIO support in MaterialX builds, the following additional opti See the [MaterialX Unit Tests](https://github.com/AcademySoftwareFoundation/MaterialX/tree/main/source/MaterialXTest) page for documentation on shader generation and render testing in GLSL, OSL, and MDL. -#### Building MaterialX Python +### Building MaterialX Python By default, the `MATERIALX_BUILD_PYTHON` option will use the active version of Python in the developer's path. To select a specific version of Python, use one or more of the following advanced options: @@ -44,25 +44,25 @@ Additional options for the generation of MaterialX Python include the following: - `MATERIALX_PYTHON_OCIO_DIR`: Path to a folder containing the default OCIO configuration to be packaged with MaterialX Python. The recommended OpenColorIO configuration for MaterialX is [ACES 1.2](https://github.com/colour-science/OpenColorIO-Configs/tree/feature/aces-1.2-config/aces_1.2). - `MATERIALX_PYTHON_PYBIND11_DIR`: Path to a folder containing the PyBind11 source to be used in building MaterialX Python. Defaults to the included PyBind11 source. -#### Building The MaterialX Viewer +### Building The MaterialX Viewer Select the `MATERIALX_BUILD_VIEWER` option to build the MaterialX Viewer. Installation will copy the **MaterialXView** executable to a `bin/` directory within the selected install folder. -#### Building API Documentation +### Building API Documentation 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. -### Installing MaterialX +## 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`. -### MaterialX Versioning +## MaterialX Versioning The MaterialX codebase uses a modified semantic versioning system where the *major* and *minor* versions match that of the corresponding MaterialX [specification](https://www.materialx.org/Specification.html), and the *build* version represents engineering advances within that specification version. MaterialX documents are similarly marked with the specification version they were authored in, and they are valid to load into any MaterialX codebase with an equal or higher specification version. -Upgrading of MaterialX documents from earlier versions is handled at import time by the Document::upgradeVersion method, which applies the syntax and node interface upgrades that have occurred in previous specification revisions. This allows the syntax conventions of MaterialX and the names and interfaces of nodes to evolve over time, without invalidating documents from earlier versions. +Upgrading of MaterialX documents from earlier versions is handled at import time by the `Document::upgradeVersion()` method, which applies the syntax and node interface upgrades that have occurred in previous specification revisions. This allows the syntax conventions of MaterialX and the names and interfaces of nodes to evolve over time, without invalidating documents from earlier versions. -### Additional Links +## Additional Links - The main [MaterialX website](http://www.materialx.org) provides background on the project's history, industry collaborations, and recent presentations. - The [Python Scripts](https://github.com/materialx/MaterialX/tree/main/python/Scripts) folder contains standalone examples of MaterialX Python code. diff --git a/documents/DeveloperGuide/ShaderGeneration.md b/documents/DeveloperGuide/ShaderGeneration.md index 01bd823ec4..c3dbc0de37 100644 --- a/documents/DeveloperGuide/ShaderGeneration.md +++ b/documents/DeveloperGuide/ShaderGeneration.md @@ -5,7 +5,7 @@ A shader generation framework is implemented as part of MaterialX. This can help Note that this system has no runtime and the output produced is source code, not binary executable code. The source code produced needs to be compiled by a shading language compiler before being executed by the renderer. See Figure 1 for a high level overview of the system. -![Shader generation with multiple shader generators](/documents/Images/shadergen.png) +![Shader generation with multiple shader generators](../Images/shadergen.png) **Figure 1**: Shader generation with multiple shader generators. @@ -43,12 +43,12 @@ Figure 2. The first option is to keep inline code in a file. The file extension -<... more types ...> +// ... more types ... // Implementation elements for node -<... more types ...> +// ... more types ... // Nodedef elements for node @@ -63,12 +63,12 @@ Figure 2. The first option is to keep inline code in a file. The file extension -<... more types ...> +// ... more types ... // Implementation elements for node -<... more types ...> +// ... more types ... ``` ```c++ // File 'mx_add.inline' contains: diff --git a/documents/DeveloperGuide/Viewer.md b/documents/DeveloperGuide/Viewer.md index 1d3a1d7dcf..63bf2dff83 100644 --- a/documents/DeveloperGuide/Viewer.md +++ b/documents/DeveloperGuide/Viewer.md @@ -2,26 +2,24 @@ The MaterialX Viewer leverages shader generation to build GLSL shaders from MaterialX graphs, rendering the results using the NanoGUI framework. The standard set of pattern and physically based shading nodes is supported, and libraries of custom nodes can be included as additional library paths. -### Example Images +## Example Images + +Marble | Copper | Plastic | Carpaint +-------|--------|---------|--------- +![MaterialX Marble material](../Images/MaterialXView_Marble.png) | ![MaterialX Copper material](../Images/MaterialXView_Copper.png) | ![MaterialX Plastic material](../Images/MaterialXView_Plastic.png) | ![MaterialX Carpaint material](../Images/MaterialXView_Carpaint.png) | **Figure 1:** Procedural and uniform materials in the MaterialX viewer -

- - - - -

+ +Tiled Brass | Tiled Wood +------------|----------- +![MaterialX TiledBrass material](../Images/MaterialXView_TiledBrass.png) | ![MaterialX TiledWood material](../Images/MaterialXView_TiledWood.png) **Figure 2:** Textured, color-space-managed materials in the MaterialX viewer -

- - -

## Building The MaterialX Viewer Select the `MATERIALX_BUILD_VIEWER` option in CMake to build the MaterialX Viewer. Installation will copy the **MaterialXView** executable to a `/bin` directory within the selected install folder. -### Summary of Viewer Options +## Summary of Viewer Options 1. **Load Mesh**: Load a new geometry in the OBJ or glTF format. 2. **Load Material**: Load a material document in the MTLX format. @@ -29,13 +27,13 @@ Select the `MATERIALX_BUILD_VIEWER` option in CMake to build the MaterialX Viewe 4. **Property Editor**: View or edit properties of the current material. 5. **Advanced Settings** : Asset and rendering options. -### Geometry +## Geometry The default display geometry for the MaterialX viewer is the Arnold Shader Ball, which was contributed to the MaterialX project by the Solid Angle team at Autodesk. To change the display geometry, click `Load Mesh` and navigate to the [Geometry](../../resources/Geometry) folder for additional models in the OBJ format. If a loaded geometry contains more than one geometric group, then a `Select Geometry` drop-down box will appear, allowing the user to select which group is active. The active geometric group will be used for subsequent actions such as material assignment and rendering property changes. -### Materials +## Materials To change the displayed material, click `Load Material` and navigate to the [Materials/Examples/StandardSurface](../../resources/Materials/Examples/StandardSurface) or [Materials/Examples/UsdPreviewSurface](../../resources/Materials/Examples/UsdPreviewSurface) folders, which contain a selection of example materials in the MTLX format. @@ -45,17 +43,17 @@ Multiple material documents can be combined in a single session by navigating to If a material document containing `look` elements is loaded into the viewer, then any material assignments within the look will be applied to geometric groups that match the specified geometry strings. See [standard_surface_look_brass_tiled.mtlx](../../resources/Materials/Examples/StandardSurface/standard_surface_look_brass_tiled.mtlx) for an example of a material document containing look elements. -### Lighting +## Lighting The default lighting environment for the viewer is the San Giuseppe Bridge environment from HDRI Haven. To load another environment into the viewer, click `Load Environment` and navigate to the [Lights](../../resources/Lights) folder, or load any HDR environment in the latitude-longitude format. If the HDR file on disk has a companion MaterialX document with a matching name, then this document will be loaded as the direct lighting rig for the environment; otherwise only indirect lighting will be rendered. If the HDR file on disk has a companion image in an `irradiance` subfolder, then this image will be loaded as the diffuse convolution of the environment; otherwise, a diffuse convolution will be generated at load-time using spherical harmonics. Shadow maps from the primary directional light may be enabled with the `Shadow Map` option under `Advanced Settings`. Ambient occlusion, if available for the given geometry, may be enabled with the `Ambient Occlusion` option. The fidelity of environment lighting may be improved by increasing the value of `Environment Samples`, though this requires additional GPU resources and can affect the interactivity of the viewer. -### Images +## Images By default, the MaterialX viewer loads and saves image files using `stb_image`, which supports commmon 8-bit formats such as JPEG, PNG, TGA, and BMP, as well as the HDR format for high-dynamic-range images. If you need access to additional image formats such as EXR and TIFF, then the MaterialX viewer can be built with support for `OpenImageIO`. To build MaterialX with OpenImageIO, check the `MATERIALX_BUILD_OIIO` option in CMake, and specify the location of your OpenImageIO installation with the `MATERIALX_OIIO_DIR` option. -### Keyboard Shortcuts +## Keyboard Shortcuts - `R`: Reload the current material from file. Hold `SHIFT` to reload all standard libraries as well. - `G`: Save the current GLSL shader source to file. @@ -74,7 +72,7 @@ By default, the MaterialX viewer loads and saves image files using `stb_image`, - `+` : Zoom in with the camera. - `-` : Zoom out with the camera. -### Command-Line Options +## Command-Line Options The following are common command-line options for MaterialXView, 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 viewer diff --git a/documents/DeveloperGuide/index.rst b/documents/DeveloperGuide/index.rst new file mode 100644 index 0000000000..8c902e5e57 --- /dev/null +++ b/documents/DeveloperGuide/index.rst @@ -0,0 +1,53 @@ +MaterialX Developer Guide +========================= + +.. toctree:: + :maxdepth: 1 + + MainPage.md + GraphEditor.md + Viewer.md + ShaderGeneration.md + + +MaterialX Python Modules +------------------------ + +.. autosummary:: + :toctree: generated + :caption: MaterialX Python Modules: + + PyMaterialXCore + PyMaterialXFormat + PyMaterialXGenGlsl + PyMaterialXGenMdl + PyMaterialXGenMsl + PyMaterialXGenOsl + PyMaterialXGenShader + PyMaterialXRender + PyMaterialXRenderGlsl + PyMaterialXRenderMsl + PyMaterialXRenderOsl + + +Import Order Dependencies +------------------------- + +Note that the order in which the MaterialX Python modules are imported matters, as there are dependencies between them: + +- :py:mod:`PyMaterialXCore` -- typically always needed + - :py:mod:`PyMaterialXFormat` -- needed for file I/O + - :py:mod:`PyMaterialXRender` -- needed for core rendering + - :py:mod:`PyMaterialXRenderGlsl` -- render using OpenGL Shading Language + - :py:mod:`PyMaterialXRenderMsl` -- render using Metal Shading Language + - :py:mod:`PyMaterialXRenderOsl` -- render using Open Shading Language +- :py:mod:`PyMaterialXGenShader` -- needed for core shader generation + - :py:mod:`PyMaterialXGenGlsl` -- generating shaders using OpenGL Shading Language + - :py:mod:`PyMaterialXGenMdl` -- generating shaders using Material Definition Language + - :py:mod:`PyMaterialXGenMsl` -- generating shaders using Metal Shading Language + - :py:mod:`PyMaterialXGenOsl` -- generating shaders using Open Shading Language + +That is to say, for example: + +- :py:mod:`PyMaterialXCore` needs to be imported before :py:mod:`PyMaterialXFormat` and :py:mod:`PyMaterialXRender` +- :py:mod:`PyMaterialXGenShader` needs to be imported before :py:mod:`PyMaterialXGenMsl` diff --git a/documents/Doxyfile.in b/documents/Doxyfile.in index 873037ef99..c92dbbed27 100644 --- a/documents/Doxyfile.in +++ b/documents/Doxyfile.in @@ -1,9 +1,9 @@ PROJECT_NAME = MaterialX -PROJECT_NUMBER = ${MATERIALX_MAJOR_VERSION}.${MATERIALX_MINOR_VERSION}.${MATERIALX_BUILD_VERSION} -PROJECT_LOGO = MaterialXLogo_200x155.png +PROJECT_NUMBER = ${MATERIALX_LIBRARY_VERSION} +PROJECT_LOGO = Images/MaterialXLogo_200x155.png -USE_MDFILE_AS_MAINPAGE = MainPage.md -HTML_EXTRA_STYLESHEET = doxygen-awesome.css +USE_MDFILE_AS_MAINPAGE = DeveloperGuide/MainPage.md +HTML_EXTRA_STYLESHEET = DoxygenAwesome/doxygen-awesome.css INPUT = ${DOXYGEN_INPUT_STR} OUTPUT_DIRECTORY = ${DOXYGEN_OUTPUT_DIR} diff --git a/documents/sphinx-conf.py.in b/documents/sphinx-conf.py.in new file mode 100644 index 0000000000..67e1d21705 --- /dev/null +++ b/documents/sphinx-conf.py.in @@ -0,0 +1,77 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'MaterialX' +copyright = '2023, MaterialX Maintainers' +author = 'MaterialX Maintainers' +release = '${MATERIALX_LIBRARY_VERSION}' + + +# -- Path Manipulation ------------------------------------------------------- + +import os +import sys +sys.path.insert(0, os.path.abspath('${MATERIALX_PYTHONPATH}')) + + +# -- Module Import Order Dependencies ---------------------------------------- + +# Make sure to import the core module before modules like `PyMaterialXFormat` +# and `PyMaterialXRender`, as otherwise, their import fails with an +# `ImportError` exception: +# ``` +# ImportError: arg(): could not convert default argument into a Python object +# (type not registered yet?). +# ``` +import PyMaterialXCore + +# Make sure to import `PyMaterialXRender` before modules like +# `PyMaterialXRenderMsl`, as otherwise, their import fails with an +# `ImportError` exception, for example: +# ``` +# ImportError: generic_type: type "MslRenderer" referenced unknown base type +# "MaterialX_v1_38_9::ShaderRenderer" +# ``` +import PyMaterialXRender + +# Make sure to import `PyMaterialXGenShader` before modules like +# `PyMaterialXGenGlsl`, as otherwise, their import fails with an `ImportError` +# exception, for example: +# ``` +# ImportError: generic_type: type "GlslShaderGenerator" referenced unknown base +# type "MaterialX_v1_38_9::HwShaderGenerator" +# ``` +import PyMaterialXGenShader + + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'myst_parser', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', +] + +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_theme_options = { + 'logo': '${MATERIALX_LOGO_FILENAME}', + 'description': 'MaterialX – An open standard for the exchange of rich material and look-development content across applications and renderers.', + 'github_button': True, + 'github_user': 'AcademySoftwareFoundation', + 'github_repo': 'MaterialX', + 'extra_nav_links': { + 'MaterialX C++ API Docs': 'https://materialx.org/docs/api/index.html', + }, +} diff --git a/documents/sphinx-custom.css b/documents/sphinx-custom.css new file mode 100644 index 0000000000..dfe1adc3ca --- /dev/null +++ b/documents/sphinx-custom.css @@ -0,0 +1,207 @@ +/* +Dark Mode colors and other variables copied from "doxygen-awesome.css". +We could potentially import the entire style sheet here, but we're only +interested in the color definitions and a select few other styles. +DoxygenAwesome is licensed under the MIT License. +*/ +html { + /* font-families. will affect all text on the website + * font-family: the normal font for text, headlines, menus + * font-family-monospace: used for preformatted text in memtitle, code, fragments + */ + --font-family: -apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,sans-serif; + --font-family-monospace: ui-monospace,SFMono-Regular,SF Mono,Menlo,Consolas,Liberation Mono,monospace; + + /* font sizes */ + --page-font-size: 15.6px; + --navigation-font-size: 14.4px; + --toc-font-size: 13.4px; + --code-font-size: 14px; /* affects code, fragment */ + --title-font-size: 22px; + + /* color for all separators on the website: hr, borders, ... */ + --separator-color: #dedede; + + /* border radius for all rounded components. Will affect many components, like dropdowns, memitems, codeblocks, ... */ + --border-radius-large: 8px; + --border-radius-small: 4px; + --border-radius-medium: 6px; + + color-scheme: dark; + + --primary-color: #1982d2; + --primary-dark-color: #86a9c4; + --primary-light-color: #4779ac; + + --box-shadow: 0 2px 8px 0 rgba(0,0,0,.30); + + --odd-color: rgba(100,100,100,.06); + + --menu-selected-background: rgba(0,0,0,.4); + + --page-background-color: #1C1D1F; + --page-foreground-color: #d2dbde; + --page-secondary-foreground-color: #859399; + --separator-color: #38393b; + --side-nav-background: #252628; + + --code-background: #2a2c2f; + + --tablehead-background: #2a2c2f; + + --blockquote-background: #222325; + --blockquote-foreground: #7e8c92; + + --warning-color: #2e1917; + --warning-color-dark: #ad2617; + --warning-color-darker: #f5b1aa; + --note-color: #3b2e04; + --note-color-dark: #f1b602; + --note-color-darker: #ceb670; + --todo-color: #163750; + --todo-color-dark: #1982D2; + --todo-color-darker: #dcf0fa; + --deprecated-color: #2e323b; + --deprecated-color-dark: #738396; + --deprecated-color-darker: #abb0bd; + --bug-color: #2a2536; + --bug-color-dark: #7661b3; + --bug-color-darker: #ae9ed6; + --invariant-color: #303a35; + --invariant-color-dark: #76ce96; + --invariant-color-darker: #cceed5; + + --fragment-background: #282c34; + --fragment-foreground: #dbe4eb; + --fragment-keyword: #cc99cd; + --fragment-keywordtype: #ab99cd; + --fragment-keywordflow: #e08000; + --fragment-token: #7ec699; + --fragment-comment: #999999; + --fragment-link: #98c0e3; + --fragment-preprocessor: #65cabe; + --fragment-linenumber-color: #cccccc; + --fragment-linenumber-background: #35393c; + --fragment-linenumber-border: #1f1f1f; +} + +/* Apply the dark mode colors on top of the default Alabastar styles */ +body, div.body { + background-color: var(--page-background-color); + color: var(--page-foreground-color); + font-family: var(--font-family); + font-size: var(--page-font-size); +} +div.sphinxsidebar { + background-color: var(--side-nav-background); +} +div.sphinxsidebar p, +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + color: var(--page-foreground-color); + font-family: var(--font-family); +} +a { + color: var(--primary-color) !important; + text-decoration: none; +} +a:link, a:visited, a:hover, a:focus, a:active { + font-weight: 500; +} +a.reference, +div.sphinxsidebar a { + text-decoration: none; + border-bottom: none; +} +a.reference:hover, +div.sphinxsidebar a:hover { + text-decoration: underline; + border-bottom: none; +} +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 +{ + font-family: var(--font-family); +} + +code, +div.fragment, +pre.fragment { + border-radius: var(--border-radius-small); + border: 1px solid var(--separator-color); + overflow: hidden; +} +code { + display: inline; + color: var(--code-foreground); + padding: 2px 6px; +} +tt, +tt.xref, +code, +code.xref, +a tt { + background-color: var(--code-background); + border-bottom: none; +} +code, +code a, +pre.fragment, +div.fragment, +div.fragment span, +div.fragment .line, +div.fragment .line a, +div.fragment .line span { + font-family: var(--font-family-monospace); + font-size: var(--code-font-size) !important; +} +code.xref, +a code { + font-weight: normal; +} +table, +table.docutils { + border: none; + border-collapse: collapse; + -webkit-box-shadow: none; + box-shadow: none; +} +table tr:nth-child(even) { + background-color: transparent; +} +table tr:nth-child(odd) { + background-color: var(--odd-color); +} +/* table header rows */ +table tr.row-odd:nth-child(odd) { + background-color: transparent; + border-bottom: 1px solid var(--separator-color); +} +table tr.row-even:nth-child(even) { + border-bottom: 1px solid var(--separator-color); +} +table.docutils td, +table.docutils th { + border: none; +} + +/* Make the MaterialX logo a little smaller */ +img.logo { + width: 60%; + height: 60%; +} + +/* Turn off auto-hyphenation in text blocks */ +div.body p, +div.body dd, +div.body li, +div.body blockquote { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; +} diff --git a/source/PyMaterialX/PyMaterialXCore/PyModule.cpp b/source/PyMaterialX/PyMaterialXCore/PyModule.cpp index e2e8a0080f..6185da225f 100644 --- a/source/PyMaterialX/PyMaterialXCore/PyModule.cpp +++ b/source/PyMaterialX/PyMaterialXCore/PyModule.cpp @@ -26,7 +26,7 @@ void bindPyVariant(py::module& mod); PYBIND11_MODULE(PyMaterialXCore, mod) { - mod.doc() = "Module containing Python bindings for the MaterialXCore library"; + mod.doc() = "Core functionality of MaterialX"; bindPyElement(mod); bindPyTraversal(mod); diff --git a/source/PyMaterialX/PyMaterialXFormat/PyModule.cpp b/source/PyMaterialX/PyMaterialXFormat/PyModule.cpp index 842087d24f..69068d429b 100644 --- a/source/PyMaterialX/PyMaterialXFormat/PyModule.cpp +++ b/source/PyMaterialX/PyMaterialXFormat/PyModule.cpp @@ -13,7 +13,7 @@ void bindPyUtil(py::module& mod); PYBIND11_MODULE(PyMaterialXFormat, mod) { - mod.doc() = "Module containing Python bindings for the MaterialXFormat library"; + mod.doc() = "Cross-platform support for working with files, paths, and environment variables"; bindPyFile(mod); bindPyXmlIo(mod); diff --git a/source/PyMaterialX/PyMaterialXGenGlsl/PyModule.cpp b/source/PyMaterialX/PyMaterialXGenGlsl/PyModule.cpp index a36b815d32..f61488cbb8 100644 --- a/source/PyMaterialX/PyMaterialXGenGlsl/PyModule.cpp +++ b/source/PyMaterialX/PyMaterialXGenGlsl/PyModule.cpp @@ -14,7 +14,7 @@ void bindPyVkShaderGenerator(py::module& mod); PYBIND11_MODULE(PyMaterialXGenGlsl, mod) { - mod.doc() = "Module containing Python bindings for the MaterialXGenGlsl library"; + mod.doc() = "Shader generation using OpenGL Shading Language"; bindPyGlslShaderGenerator(mod); bindPyGlslResourceBindingContext(mod); diff --git a/source/PyMaterialX/PyMaterialXGenMdl/PyModule.cpp b/source/PyMaterialX/PyMaterialXGenMdl/PyModule.cpp index 020c944e63..69479788c3 100644 --- a/source/PyMaterialX/PyMaterialXGenMdl/PyModule.cpp +++ b/source/PyMaterialX/PyMaterialXGenMdl/PyModule.cpp @@ -11,7 +11,7 @@ void bindPyMdlShaderGenerator(py::module& mod); PYBIND11_MODULE(PyMaterialXGenMdl, mod) { - mod.doc() = "Module containing Python bindings for the MaterialXGenMdl library"; + mod.doc() = "Shader generation using Material Definition Language"; bindPyMdlShaderGenerator(mod); }; diff --git a/source/PyMaterialX/PyMaterialXGenMsl/PyModule.cpp b/source/PyMaterialX/PyMaterialXGenMsl/PyModule.cpp index 6eda44871b..a1098f138c 100644 --- a/source/PyMaterialX/PyMaterialXGenMsl/PyModule.cpp +++ b/source/PyMaterialX/PyMaterialXGenMsl/PyModule.cpp @@ -12,7 +12,7 @@ void bindPyMslResourceBindingContext(py::module &mod); PYBIND11_MODULE(PyMaterialXGenMsl, mod) { - mod.doc() = "Module containing Python bindings for the MaterialXGenMsl library"; + mod.doc() = "Shader generation using Metal Shading Language"; bindPyMslShaderGenerator(mod); bindPyMslResourceBindingContext(mod); diff --git a/source/PyMaterialX/PyMaterialXGenOsl/PyModule.cpp b/source/PyMaterialX/PyMaterialXGenOsl/PyModule.cpp index d772d18b6a..6fc0237f87 100644 --- a/source/PyMaterialX/PyMaterialXGenOsl/PyModule.cpp +++ b/source/PyMaterialX/PyMaterialXGenOsl/PyModule.cpp @@ -11,7 +11,7 @@ void bindPyOslShaderGenerator(py::module& mod); PYBIND11_MODULE(PyMaterialXGenOsl, mod) { - mod.doc() = "Module containing Python bindings for the MaterialXGenOsl library"; + mod.doc() = "Shader generation using Open Shading Language"; bindPyOslShaderGenerator(mod); } diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyModule.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyModule.cpp index f3dc613bff..66abde6878 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyModule.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyModule.cpp @@ -24,7 +24,7 @@ void bindPyUnitSystem(py::module& mod); PYBIND11_MODULE(PyMaterialXGenShader, mod) { - mod.doc() = "Module containing Python bindings for the MaterialXGenShader library"; + mod.doc() = "Core functionality for shader generation"; bindPyColorManagement(mod); bindPyShaderPort(mod); diff --git a/source/PyMaterialX/PyMaterialXRender/PyModule.cpp b/source/PyMaterialX/PyMaterialXRender/PyModule.cpp index 1c60142346..c8ac371c23 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyModule.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyModule.cpp @@ -23,7 +23,7 @@ void bindPyCgltfLoader(py::module& mod); PYBIND11_MODULE(PyMaterialXRender, mod) { - mod.doc() = "Module containing Python bindings for the MaterialXRender library"; + mod.doc() = "Core rendering functionality for MaterialX"; bindPyMesh(mod); bindPyGeometryHandler(mod); diff --git a/source/PyMaterialX/PyMaterialXRenderGlsl/PyModule.cpp b/source/PyMaterialX/PyMaterialXRenderGlsl/PyModule.cpp index 32fb79239d..f87854fde4 100644 --- a/source/PyMaterialX/PyMaterialXRenderGlsl/PyModule.cpp +++ b/source/PyMaterialX/PyMaterialXRenderGlsl/PyModule.cpp @@ -14,7 +14,7 @@ void bindPyTextureBaker(py::module& mod); PYBIND11_MODULE(PyMaterialXRenderGlsl, mod) { - mod.doc() = "Module containing Python bindings for the MaterialXRenderGlsl library"; + mod.doc() = "Rendering materials using OpenGL Shading Language"; bindPyGlslProgram(mod); bindPyGlslRenderer(mod); diff --git a/source/PyMaterialX/PyMaterialXRenderMsl/PyModule.mm b/source/PyMaterialX/PyMaterialXRenderMsl/PyModule.mm index 10b440d21c..1e120bf1c0 100644 --- a/source/PyMaterialX/PyMaterialXRenderMsl/PyModule.mm +++ b/source/PyMaterialX/PyMaterialXRenderMsl/PyModule.mm @@ -14,7 +14,7 @@ PYBIND11_MODULE(PyMaterialXRenderMsl, mod) { - mod.doc() = "Module containing Python bindings for the MaterialXRenderMsl library"; + mod.doc() = "Rendering materials using Metal Shading Language"; bindPyMslProgram(mod); bindPyMslRenderer(mod); diff --git a/source/PyMaterialX/PyMaterialXRenderOsl/PyModule.cpp b/source/PyMaterialX/PyMaterialXRenderOsl/PyModule.cpp index 15610066f3..31ec2b1b65 100644 --- a/source/PyMaterialX/PyMaterialXRenderOsl/PyModule.cpp +++ b/source/PyMaterialX/PyMaterialXRenderOsl/PyModule.cpp @@ -11,7 +11,7 @@ void bindPyOslRenderer(py::module& mod); PYBIND11_MODULE(PyMaterialXRenderOsl, mod) { - mod.doc() = "Module containing Python bindings for the MaterialXRenderOsl library"; + mod.doc() = "Rendering materials using Open Shading Language"; bindPyOslRenderer(mod); }