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

…RenderGlsl.

source/PyMaterialX/PyMaterialXRenderGlsl/PyGLTextureHandler.cpp

@@ -18,5 +18,10 @@ void bindPyGLTextureHandler(py::module& mod)
         .def("unbindImage", &mx::GLTextureHandler::unbindImage)
         .def("createRenderResources", &mx::GLTextureHandler::createRenderResources)
         .def("releaseRenderResources", &mx::GLTextureHandler::releaseRenderResources,
-            py::arg("image") = nullptr);
+            py::arg("image") = nullptr)
+        .doc() = R"docstring(
+    An OpenGL texture handler class.
+
+    :see: https://materialx.org/docs/api/class_g_l_texture_handler.html
+)docstring";
 }

source/PyMaterialX/PyMaterialXRenderGlsl/PyGlslProgram.cpp

@@ -38,7 +38,15 @@ void bindPyGlslProgram(py::module& mod)
         .def("bindViewInformation", &mx::GlslProgram::bindViewInformation)
         .def("bindTimeAndFrame", &mx::GlslProgram::bindTimeAndFrame,
             py::arg("time") = 1.0f, py::arg("frame") = 1.0f)
-        .def("unbind", &mx::GlslProgram::unbind);
+        .def("unbind", &mx::GlslProgram::unbind)
+        .doc() = R"docstring(
+    Class representing an executable GLSL 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.
+
+    :see: https://materialx.org/docs/api/class_glsl_program.html
+)docstring";
 
     py::class_<mx::GlslProgram::Input>(mod, "Input")
         .def_readwrite_static("INVALID_OPENGL_TYPE", &mx::GlslProgram::Input::INVALID_OPENGL_TYPE)
@@ -49,5 +57,14 @@ void bindPyGlslProgram(py::module& mod)
         .def_readwrite("value", &mx::GlslProgram::Input::value)
         .def_readwrite("isConstant", &mx::GlslProgram::Input::isConstant)
         .def_readwrite("path", &mx::GlslProgram::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.
+
+    :see: https://materialx.org/docs/api/struct_glsl_program_1_1_input.html
+)docstring";
 }

source/PyMaterialX/PyMaterialXRenderGlsl/PyGlslRenderer.cpp

@@ -21,5 +21,26 @@ void bindPyGlslRenderer(py::module& mod)
         .def("render", &mx::GlslRenderer::render)
         .def("renderTextureSpace", &mx::GlslRenderer::renderTextureSpace)
         .def("captureImage", &mx::GlslRenderer::captureImage)
-        .def("getProgram", &mx::GlslRenderer::getProgram);
+        .def("getProgram", &mx::GlslRenderer::getProgram)
+        .doc() = R"docstring(
+    Helper class for rendering generated GLSL 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 attached to a GLSL
+          shader program.
+        - Introspection: The compiled shader program is examined for uniforms
+          and attributes.
+        - Binding: Uniforms and attributes which match the predefined variables
+          generated the GLSL 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.
+
+    :see: https://materialx.org/docs/api/class_glsl_renderer.html
+)docstring";
 }

source/PyMaterialX/PyMaterialXRenderGlsl/PyModule.cpp

@@ -14,7 +14,24 @@ void bindPyTextureBaker(py::module& mod);
 
 PYBIND11_MODULE(PyMaterialXRenderGlsl, mod)
 {
-    mod.doc() = "Rendering materials using OpenGL Shading Language";
+    mod.doc() = R"docstring(
+    Rendering materials using OpenGL Shading Language.
+
+    :see: https://www.opengl.org
+    :see: https://www.vulkan.org
+
+    GLSL Rendering Classes
+    ----------------------
+
+    .. autosummary::
+        :toctree: glsl-rendering
+
+        GlslRenderer
+        GlslProgram
+        GLTextureHandler
+        Input
+        TextureBaker
+)docstring";
 
     // PyMaterialXRenderGlsl depends on types defined in PyMaterialXRender
     pybind11::module::import("PyMaterialXRender");

source/PyMaterialX/PyMaterialXRenderGlsl/PyTextureBaker.cpp

@@ -43,5 +43,10 @@ void bindPyTextureBaker(py::module& mod)
         .def("setupUnitSystem", &mx::TextureBakerGlsl::setupUnitSystem)
         .def("bakeMaterialToDoc", &mx::TextureBakerGlsl::bakeMaterialToDoc)
         .def("bakeAllMaterials", &mx::TextureBakerGlsl::bakeAllMaterials)
-        .def("writeDocumentPerMaterial", &mx::TextureBakerGlsl::writeDocumentPerMaterial);
+        .def("writeDocumentPerMaterial", &mx::TextureBakerGlsl::writeDocumentPerMaterial)
+        .doc() = R"docstring(
+    Class implementing a texture baker based on GLSL shader generation.
+
+    :see: https://materialx.org/docs/api/class_texture_baker_glsl.html
+)docstring";
 }