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

…GenGlsl.
AcademySoftwareFoundation · Oct 18, 2023 · 67bb241 · 67bb241
1 parent 133a0b4
commit 67bb241
Show file tree

Hide file tree

Showing 2 changed files with 55 additions and 5 deletions.
diff --git a/source/PyMaterialX/PyMaterialXGenGlsl/PyGlslShaderGenerator.cpp b/source/PyMaterialX/PyMaterialXGenGlsl/PyGlslShaderGenerator.cpp
@@ -26,7 +26,13 @@ void bindPyGlslShaderGenerator(py::module& mod)
         .def(py::init<>())
         .def("generate", &mx::GlslShaderGenerator::generate)
         .def("getTarget", &mx::GlslShaderGenerator::getTarget)
-        .def("getVersion", &mx::GlslShaderGenerator::getVersion);
+        .def("getVersion", &mx::GlslShaderGenerator::getVersion)
+        .doc() = R"docstring(
+    Base class for GLSL (OpenGL Shading Language) code generation.
+    A generator for a specific GLSL target should be derived from this class.
+
+    :see: https://materialx.org/docs/api/class_glsl_shader_generator.html
+)docstring";
 }
 
 void bindPyGlslResourceBindingContext(py::module &mod)
@@ -35,7 +41,12 @@ void bindPyGlslResourceBindingContext(py::module &mod)
         .def_static("create", &mx::GlslResourceBindingContext::create)
         .def(py::init<size_t, size_t>())
         .def("emitDirectives", &mx::GlslResourceBindingContext::emitDirectives)
-        .def("emitResourceBindings", &mx::GlslResourceBindingContext::emitResourceBindings);
+        .def("emitResourceBindings", &mx::GlslResourceBindingContext::emitResourceBindings)
+        .doc() = R"docstring(
+    Class representing a resource binding for GLSL shader resources.
+
+    :see: https://materialx.org/docs/api/class_glsl_resource_binding_context.html
+)docstring";
 }
 
 // Essl shader generator bindings
@@ -47,7 +58,12 @@ void bindPyEsslShaderGenerator(py::module& mod)
         .def(py::init<>())
         .def("generate", &mx::EsslShaderGenerator::generate)
         .def("getTarget", &mx::EsslShaderGenerator::getTarget)
-        .def("getVersion", &mx::EsslShaderGenerator::getVersion);
+        .def("getVersion", &mx::EsslShaderGenerator::getVersion)
+        .doc() = R"docstring(
+    Class implementing an ESSL (OpenGL ES Shading Language) shader generator
+
+    :see: https://materialx.org/docs/api/class_essl_shader_generator.html
+)docstring";
 }
 
 // Glsl Vulkan shader generator bindings
@@ -59,5 +75,10 @@ void bindPyVkShaderGenerator(py::module& mod)
         .def(py::init<>())
         .def("generate", &mx::VkShaderGenerator::generate)
         .def("getTarget", &mx::VkShaderGenerator::getTarget)
-        .def("getVersion", &mx::VkShaderGenerator::getVersion);
+        .def("getVersion", &mx::VkShaderGenerator::getVersion)
+        .doc() = R"docstring(
+    Class implementing a Vulkan GLSL shader generator.
+
+    :see: https://materialx.org/docs/api/class_vk_shader_generator.html
+)docstring";
 }
diff --git a/source/PyMaterialX/PyMaterialXGenGlsl/PyModule.cpp b/source/PyMaterialX/PyMaterialXGenGlsl/PyModule.cpp
@@ -14,7 +14,36 @@ void bindPyVkShaderGenerator(py::module& mod);
 
 PYBIND11_MODULE(PyMaterialXGenGlsl, mod)
 {
-    mod.doc() = "Shader generation using OpenGL Shading Language";
+    mod.doc() = R"docstring(
+    Shader generation using OpenGL Shading Language.
+
+    :see: https://www.opengl.org
+    :see: https://www.vulkan.org
+
+    GLSL Shader Generation Classes
+    ------------------------------
+
+    **Class Hierarchy**
+
+    * `PyMaterialXGenShader.ShaderGenerator`
+        * `PyMaterialXGenShader.HwShaderGenerator`
+            * `GlslShaderGenerator`
+                * `EsslShaderGenerator`
+                * `VkShaderGenerator`
+    * `PyMaterialXGenShader.GenUserData`
+        * `PyMaterialXGenShader.HwResourceBindingContext`
+            * `GlslResourceBindingContext`
+
+    **Class Index**
+
+    .. autosummary::
+        :toctree: glsl-shader-generators
+
+        GlslShaderGenerator
+        EsslShaderGenerator
+        VkShaderGenerator
+        GlslResourceBindingContext
+)docstring";
 
     // PyMaterialXGenGlsl depends on types defined in PyMaterialXGenShader
     pybind11::module::import("PyMaterialXGenShader");