Docstrings for PyMaterialXGenShader. (#1567)

Signed-off-by: Stefan Habel <19556655+StefanHabel@users.noreply.github.com>
AcademySoftwareFoundation · Oct 31, 2023 · 6253abc · 6253abc
1 parent 77ca69c
commit 6253abc
Show file tree

Hide file tree

Showing 12 changed files with 844 additions and 184 deletions.
diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyColorManagement.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyColorManagement.cpp
@@ -44,30 +44,82 @@ class PyColorManagementSystem : public mx::ColorManagementSystem
 void bindPyColorManagement(py::module& mod)
 {
     py::class_<mx::ColorSpaceTransform>(mod, "ColorSpaceTransform")
-        .def(py::init<const std::string&, const std::string&, const mx::TypeDesc*>())
-        .def_readwrite("sourceSpace", &mx::ColorSpaceTransform::sourceSpace)
-        .def_readwrite("targetSpace", &mx::ColorSpaceTransform::targetSpace)
-        .def_readwrite("type", &mx::ColorSpaceTransform::type)
+
+        .def(py::init<const std::string&, const std::string&, const mx::TypeDesc*>(),
+             py::arg("sourceSpace"),
+             py::arg("targetSpace"),
+             py::arg("typeDesc"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Initialize an instance of this class using the given source space, target
+    space, and type descriptor.
+)docstring"))
+
+        .def_readwrite("sourceSpace", &mx::ColorSpaceTransform::sourceSpace,
+                       PYMATERIALX_DOCSTRING(R"docstring(
+    The source color space of the color space transform.
+)docstring"))
+
+        .def_readwrite("targetSpace", &mx::ColorSpaceTransform::targetSpace,
+                       PYMATERIALX_DOCSTRING(R"docstring(
+    The target color space of the color space transform.
+)docstring"))
+
+        .def_readwrite("typeDesc", &mx::ColorSpaceTransform::type,
+                       PYMATERIALX_DOCSTRING(R"docstring(
+    The type descriptor of the color space transform.
+)docstring"))
+
         .doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Structure that represents color space transform information.
 
     :see: https://materialx.org/docs/api/struct_color_space_transform.html
 )docstring");
 
     py::class_<mx::ColorManagementSystem, PyColorManagementSystem, mx::ColorManagementSystemPtr>(mod, "ColorManagementSystem")
-        .def(py::init<>())
-        .def("getName", &mx::ColorManagementSystem::getName)
-        .def("loadLibrary", &mx::ColorManagementSystem::loadLibrary)
-        .def("supportsTransform", &mx::ColorManagementSystem::supportsTransform)
+
+        .def(py::init<>(),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Initialize an instance of this class.
+)docstring"))
+
+        .def("getName", &mx::ColorManagementSystem::getName,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return the name of the color management system.
+)docstring"))
+
+        .def("loadLibrary", &mx::ColorManagementSystem::loadLibrary,
+             py::arg("document"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Load a library of implementations from the provided `document`,
+    replacing any previously loaded content.
+)docstring"))
+
+        .def("supportsTransform", &mx::ColorManagementSystem::supportsTransform,
+             py::arg("transform"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Returns whether this color management system supports the provided
+    `transform`.
+)docstring"))
+
         .doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Abstract base class for color management systems.
 
     :see: https://materialx.org/docs/api/class_color_management_system.html
 )docstring");
 
     py::class_<mx::DefaultColorManagementSystem, mx::DefaultColorManagementSystemPtr, mx::ColorManagementSystem>(mod, "DefaultColorManagementSystem")
-        .def_static("create", &mx::DefaultColorManagementSystem::create)
-        .def("getName", &mx::DefaultColorManagementSystem::getName)
+
+        .def_static("create", &mx::DefaultColorManagementSystem::create,
+                    py::arg("target"),
+                    PYMATERIALX_DOCSTRING(R"docstring(
+    Create a new `DefaultColorManagementSystem` instance.
+)docstring"))
+
+        .def("getName", &mx::DefaultColorManagementSystem::getName,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return the name of the default color management system.
+)docstring"))
+
         .doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Class for a default color management system.
 

diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyGenContext.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyGenContext.cpp
@@ -14,6 +14,7 @@ namespace mx = MaterialX;
 void bindPyGenContext(py::module& mod)
 {
     py::class_<mx::ApplicationVariableHandler>(mod, "ApplicationVariableHandler")
+
         .doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Class representing a function to allow for handling of application
     variables for a given node.
@@ -22,26 +23,92 @@ void bindPyGenContext(py::module& mod)
 )docstring");
 
     py::class_<mx::GenContext, mx::GenContextPtr>(mod, "GenContext")
-        .def(py::init<mx::ShaderGeneratorPtr>())
-        .def("getShaderGenerator", &mx::GenContext::getShaderGenerator)
-        .def("getOptions", static_cast<mx::GenOptions & (mx::GenContext::*)()>(&mx::GenContext::getOptions), py::return_value_policy::reference)
-        .def("registerSourceCodeSearchPath", static_cast<void (mx::GenContext::*)(const mx::FilePath&)>(&mx::GenContext::registerSourceCodeSearchPath))
-        .def("registerSourceCodeSearchPath", static_cast<void (mx::GenContext::*)(const mx::FileSearchPath&)>(&mx::GenContext::registerSourceCodeSearchPath))
-        .def("resolveSourceFile", &mx::GenContext::resolveSourceFile)
-        .def("pushUserData", &mx::GenContext::pushUserData)
-        .def("setApplicationVariableHandler", &mx::GenContext::setApplicationVariableHandler)
-        .def("getApplicationVariableHandler", &mx::GenContext::getApplicationVariableHandler)
+
+        .def(py::init<mx::ShaderGeneratorPtr>(),
+             py::arg("shaderGenerator"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Initialize an instance of this class using the given shader generator.
+)docstring"))
+
+        .def("getShaderGenerator", &mx::GenContext::getShaderGenerator,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return the context's shader generator.
+)docstring"))
+
+        .def("getOptions",
+             static_cast<mx::GenOptions& (mx::GenContext::*)()>(&mx::GenContext::getOptions),
+             py::return_value_policy::reference,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return shader generation options.
+)docstring"))
+
+        .def("registerSourceCodeSearchPath",
+             static_cast<void (mx::GenContext::*)(const mx::FilePath&)>(&mx::GenContext::registerSourceCodeSearchPath),
+             py::arg("path"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Register a user search path for finding source code during code generation.
+
+    :see: `resolveSourceFile()`
+)docstring"))
+
+        .def("registerSourceCodeSearchPath",
+             static_cast<void (mx::GenContext::*)(const mx::FileSearchPath&)>(&mx::GenContext::registerSourceCodeSearchPath),
+             py::arg("path"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Register a user search path for finding source code during code generation.
+
+    :see: `resolveSourceFile()`
+)docstring"))
+
+        .def("resolveSourceFile", &mx::GenContext::resolveSourceFile,
+             py::arg("filename"),
+             py::arg("localPath"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Resolve a source code filename, first checking the given local path,
+    then checking any file paths registered by the user.
+
+    :see: `registerSourceCodeSearchPath()`
+)docstring"))
+
+        .def("pushUserData", &mx::GenContext::pushUserData,
+             py::arg("name"),
+             py::arg("data"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Add user data to the context to make it available during shader generation.
+)docstring"))
+
+        .def("setApplicationVariableHandler",
+             &mx::GenContext::setApplicationVariableHandler,
+             py::arg("handler"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Set handler for application variables.
+)docstring"))
+
+        .def("getApplicationVariableHandler",
+             &mx::GenContext::getApplicationVariableHandler,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return handler for application variables.
+)docstring"))
+
         .doc() = PYMATERIALX_DOCSTRING(R"docstring(
     A context class for shader generation.
 
+    Used for thread-local storage of data needed during shader generation.
+
     :see: https://materialx.org/docs/api/class_gen_context.html
 )docstring");
 }
 
 void bindPyGenUserData(py::module& mod)
 {
     py::class_<mx::GenUserData, mx::GenUserDataPtr>(mod, "GenUserData")
-        .def("getSelf", static_cast<mx::GenUserDataPtr(mx::GenUserData::*)()>(&mx::GenUserData::getSelf))
+
+        .def("getSelf",
+             static_cast<mx::GenUserDataPtr(mx::GenUserData::*)()>(&mx::GenUserData::getSelf),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return this object.
+)docstring"))
+
         .doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Base class for custom user data needed during shader generation.