Sphinx Python Documentation (#1567) - Added docstrings to PyMaterialX…

…RenderMsl.

source/PyMaterialX/PyMaterialXRenderMsl/PyMetalTextureHandler.mm

@@ -18,5 +18,8 @@ void bindPyMetalTextureHandler(py::module& mod)
         .def("unbindImage", &mx::MetalTextureHandler::unbindImage)
         .def("createRenderResources", &mx::MetalTextureHandler::createRenderResources)
         .def("releaseRenderResources", &mx::MetalTextureHandler::releaseRenderResources,
-            py::arg("image") = nullptr);
+            py::arg("image") = nullptr)
+        .doc() = R"docstring(
+    A Metal texture handler class.
+)docstring";
 }

source/PyMaterialX/PyMaterialXRenderMsl/PyModule.mm

@@ -14,7 +14,24 @@
 
 PYBIND11_MODULE(PyMaterialXRenderMsl, mod)
 {
-    mod.doc() = "Rendering materials using Metal Shading Language";
+    mod.doc() = R"docstring(
+    Rendering materials using Metal Shading Language.
+
+    :see: https://developer.apple.com/metal/
+    :see: https://developer.apple.com/documentation/metal
+
+    Metal Rendering Classes
+    -----------------------
+
+    .. autosummary::
+        :toctree: metal-rendering
+
+        MslRenderer
+        MslProgram
+        MetalTextureHandler
+        Input
+        TextureBaker
+)docstring";
 
     // PyMaterialXRenderMsl depends on types defined in PyMaterialXRender
     pybind11::module::import("PyMaterialXRender");

source/PyMaterialX/PyMaterialXRenderMsl/PyMslProgram.mm

@@ -34,7 +34,13 @@ void bindPyMslProgram(py::module& mod)
         .def("bindLighting", &mx::MslProgram::bindLighting)
         .def("bindViewInformation", &mx::MslProgram::bindViewInformation)
         .def("bindTimeAndFrame", &mx::MslProgram::bindTimeAndFrame,
-             py::arg("time") = 1.0f, py::arg("frame") = 1.0f);
+             py::arg("time") = 1.0f, py::arg("frame") = 1.0f)
+        .doc() = R"docstring(
+    Class representing an executable MSL program.
+
+    There are two main interfaces which can be used: one which takes in a
+    `HwShader`, and one which allows for explicit setting of shader stage code.
+)docstring";
 
     py::class_<mx::MslProgram::Input>(mod, "Input")
         .def_readwrite("location", &mx::MslProgram::Input::location)
@@ -43,5 +49,12 @@ void bindPyMslProgram(py::module& mod)
         .def_readwrite("value", &mx::MslProgram::Input::value)
         .def_readwrite("isConstant", &mx::MslProgram::Input::isConstant)
         .def_readwrite("path", &mx::MslProgram::Input::path)
-        .def(py::init<int, int, int, std::string>());
+        .def(py::init<int, int, int, std::string>())
+        .doc() = R"docstring(
+    Class representing a structure to hold information about program inputs.
+
+    The structure is populated by directly scanning the program so may not contain
+    some inputs listed on any associated `HwShader` as those inputs may have been
+    optimized out if they are unused.
+)docstring";
 }

source/PyMaterialX/PyMaterialXRenderMsl/PyMslRenderer.mm

@@ -22,5 +22,24 @@ void bindPyMslRenderer(py::module& mod)
         .def("render", &mx::MslRenderer::render)
         .def("renderTextureSpace", &mx::MslRenderer::renderTextureSpace)
         .def("captureImage", &mx::MslRenderer::captureImage)
-        .def("getProgram", &mx::MslRenderer::getProgram);
+        .def("getProgram", &mx::MslRenderer::getProgram)
+        .doc() = R"docstring(
+    Helper class for rendering generated MSL code to produce images.
+
+    There are two main interfaces which can be used: one which takes in a
+    `HwShader`, and one which allows for explicit setting of shader stage code.
+
+    The main services provided are:
+        - Validation: All shader stages are compiled and atteched to an MSL
+          shader program.
+        - Introspection: The compiled shader program is examined for uniforms
+          and attributes.
+        - Binding: Uniforms and attributes which match the predefined variables
+          generated the MSL code generator will have values assigned to this.
+          This includes matrices, attribute streams, and textures.
+        - Rendering: The program with bound inputs will be used to drawing
+          geometry to an offscreen buffer.
+          An interface is provided to save this offscreen buffer to disk using
+          an externally defined image handler.
+)docstring";
 }

source/PyMaterialX/PyMaterialXRenderMsl/PyTextureBaker.mm

@@ -43,5 +43,11 @@ void bindPyTextureBaker(py::module& mod)
         .def("setupUnitSystem", &mx::TextureBakerMsl::setupUnitSystem)
         .def("bakeMaterialToDoc", &mx::TextureBakerMsl::bakeMaterialToDoc)
         .def("bakeAllMaterials", &mx::TextureBakerMsl::bakeAllMaterials)
-        .def("writeDocumentPerMaterial", &mx::TextureBakerMsl::writeDocumentPerMaterial);
+        .def("writeDocumentPerMaterial", &mx::TextureBakerMsl::writeDocumentPerMaterial)
+        .doc() = R"docstring(
+    A helper class for baking procedural material content to textures.
+
+    :todo: Add support for graphs containing geometric nodes such as position
+        and normal.
+)docstring";
 }