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

…Core.

source/PyMaterialX/PyMaterialXCore/PyDefinition.cpp

@@ -32,7 +32,15 @@ void bindPyDefinition(py::module& mod)
         .def_readonly_static("GEOMETRIC_NODE_GROUP", &mx::NodeDef::GEOMETRIC_NODE_GROUP)
         .def_readonly_static("ADJUSTMENT_NODE_GROUP", &mx::NodeDef::ADJUSTMENT_NODE_GROUP)
         .def_readonly_static("CONDITIONAL_NODE_GROUP", &mx::NodeDef::CONDITIONAL_NODE_GROUP)
-        .def_readonly_static("ORGANIZATION_NODE_GROUP", &mx::NodeDef::ORGANIZATION_NODE_GROUP);
+        .def_readonly_static("ORGANIZATION_NODE_GROUP", &mx::NodeDef::ORGANIZATION_NODE_GROUP)
+        .doc() = R"docstring(
+    Class representing a node definition element within a `Document`.
+
+    A `NodeDef` provides the declaration of a node interface, which may then
+    be instantiated as a `Node`.
+
+    :see: https://materialx.org/docs/api/class_node_def.html
+)docstring";
 
     py::class_<mx::Implementation, mx::ImplementationPtr, mx::InterfaceElement>(mod, "Implementation")
         .def("setFile", &mx::Implementation::setFile)
@@ -48,7 +56,16 @@ void bindPyDefinition(py::module& mod)
         .def("getNodeGraph", &mx::Implementation::getNodeGraph)
         .def_readonly_static("CATEGORY", &mx::Implementation::CATEGORY)
         .def_readonly_static("FILE_ATTRIBUTE", &mx::Implementation::FILE_ATTRIBUTE)
-        .def_readonly_static("FUNCTION_ATTRIBUTE", &mx::Implementation::FUNCTION_ATTRIBUTE);
+        .def_readonly_static("FUNCTION_ATTRIBUTE", &mx::Implementation::FUNCTION_ATTRIBUTE)
+        .doc() = R"docstring(
+    Class representing an implementation element within a `Document`.
+
+    An `Implementation` is used to associate external source code with a specific
+    `NodeDef`, providing a definition for the node that may either be universal or
+    restricted to a specific target.
+
+    :see: https://materialx.org/docs/api/class_implementation.html
+)docstring";
 
     py::class_<mx::TypeDef, mx::TypeDefPtr, mx::Element>(mod, "TypeDef")
         .def("setSemantic", &mx::TypeDef::setSemantic)
@@ -64,13 +81,28 @@ void bindPyDefinition(py::module& mod)
         .def("removeMember", &mx::TypeDef::removeMember)
         .def_readonly_static("CATEGORY", &mx::TypeDef::CATEGORY)
         .def_readonly_static("SEMANTIC_ATTRIBUTE", &mx::TypeDef::SEMANTIC_ATTRIBUTE)
-        .def_readonly_static("CONTEXT_ATTRIBUTE", &mx::TypeDef::CONTEXT_ATTRIBUTE);
+        .def_readonly_static("CONTEXT_ATTRIBUTE", &mx::TypeDef::CONTEXT_ATTRIBUTE)
+        .doc() = R"docstring(
+    Class representing a type definition element within a `Document`.
+
+    :see: https://materialx.org/docs/api/class_type_def.html
+)docstring";
 
     py::class_<mx::Member, mx::MemberPtr, mx::TypedElement>(mod, "Member")
-        .def_readonly_static("CATEGORY", &mx::TypeDef::CATEGORY);
+        .def_readonly_static("CATEGORY", &mx::TypeDef::CATEGORY)
+        .doc() = R"docstring(
+    Class representing a member element within a `TypeDef`.
+
+    :see: https://materialx.org/docs/api/class_member.html
+)docstring";
 
     py::class_<mx::Unit, mx::UnitPtr, mx::Element>(mod, "Unit")
-        .def_readonly_static("CATEGORY", &mx::Unit::CATEGORY);
+        .def_readonly_static("CATEGORY", &mx::Unit::CATEGORY)
+        .doc() = R"docstring(
+    Class representing a unit declaration element within a `UnitDef`.
+
+    :see: https://materialx.org/docs/api/class_unit.html
+)docstring";
 
     py::class_<mx::UnitDef, mx::UnitDefPtr, mx::Element>(mod, "UnitDef")
         .def("setUnitType", &mx::UnitDef::hasUnitType)
@@ -80,24 +112,44 @@ void bindPyDefinition(py::module& mod)
         .def("getUnit", &mx::UnitDef::getUnit)
         .def("getUnits", &mx::UnitDef::getUnits)
         .def_readonly_static("CATEGORY", &mx::UnitDef::CATEGORY)
-        .def_readonly_static("UNITTYPE_ATTRIBUTE", &mx::UnitDef::UNITTYPE_ATTRIBUTE);
+        .def_readonly_static("UNITTYPE_ATTRIBUTE", &mx::UnitDef::UNITTYPE_ATTRIBUTE)
+        .doc() = R"docstring(
+    Class representing a unit definition element within a `Document`.
+
+    :see: https://materialx.org/docs/api/class_unit_def.html
+)docstring";
 
     py::class_<mx::UnitTypeDef, mx::UnitTypeDefPtr, mx::Element>(mod, "UnitTypeDef")
         .def("getUnitDefs", &mx::UnitTypeDef::getUnitDefs)
-        .def_readonly_static("CATEGORY", &mx::UnitTypeDef::CATEGORY);
+        .def_readonly_static("CATEGORY", &mx::UnitTypeDef::CATEGORY)
+        .doc() = R"docstring(
+    Class representing a unit type definition element within a `Document`.
+
+    :see: https://materialx.org/docs/api/class_unit_type_def.html
+)docstring";
 
     py::class_<mx::AttributeDef, mx::AttributeDefPtr, mx::TypedElement>(mod, "AttributeDef")
         .def("setAttrName", &mx::AttributeDef::setAttrName)
         .def("hasAttrName", &mx::AttributeDef::hasAttrName)
         .def("getAttrName", &mx::AttributeDef::getAttrName)
         .def("setValueString", &mx::AttributeDef::setValueString)
         .def("hasValueString", &mx::AttributeDef::hasValueString)
-        .def("getValueString", &mx::AttributeDef::getValueString) 
-        .def("setExportable", &mx::AttributeDef::setExportable)         
-        .def("getExportable", &mx::AttributeDef::getExportable)         
-        .def_readonly_static("CATEGORY", &mx::AttributeDef::CATEGORY);
+        .def("getValueString", &mx::AttributeDef::getValueString)
+        .def("setExportable", &mx::AttributeDef::setExportable)
+        .def("getExportable", &mx::AttributeDef::getExportable)
+        .def_readonly_static("CATEGORY", &mx::AttributeDef::CATEGORY)
+        .doc() = R"docstring(
+    Class representing an attribute definition element within a `Document`.
+
+    :see: https://materialx.org/docs/api/class_attribute_def.html
+)docstring";
 
     py::class_<mx::TargetDef, mx::TargetDefPtr, mx::TypedElement>(mod, "TargetDef")
         .def("getMatchingTargets", &mx::TargetDef::getMatchingTargets)
-        .def_readonly_static("CATEGORY", &mx::TargetDef::CATEGORY);
+        .def_readonly_static("CATEGORY", &mx::TargetDef::CATEGORY)
+        .doc() = R"docstring(
+    Class representing the definition of an implementation target as a `TypedElement`.
+
+    :see: https://materialx.org/docs/api/class_target_def.html
+)docstring";
 }

source/PyMaterialX/PyMaterialXCore/PyDocument.cpp

@@ -12,7 +12,11 @@ namespace mx = MaterialX;
 
 void bindPyDocument(py::module& mod)
 {
-    mod.def("createDocument", &mx::createDocument);
+    mod.def("createDocument", &mx::createDocument,
+            R"docstring(
+    Create a MaterialX `Document` instance, which represents the top-level
+    element in the MaterialX ownership hierarchy.
+)docstring");
 
     py::class_<mx::Document, mx::DocumentPtr, mx::GraphElement>(mod, "Document")
         .def("initialize", &mx::Document::initialize)
@@ -102,5 +106,11 @@ void bindPyDocument(py::module& mod)
         .def("getColorManagementSystem", &mx::Document::getColorManagementSystem)
         .def("setColorManagementConfig", &mx::Document::setColorManagementConfig)
         .def("hasColorManagementConfig", &mx::Document::hasColorManagementConfig)
-        .def("getColorManagementConfig", &mx::Document::getColorManagementConfig);
+        .def("getColorManagementConfig", &mx::Document::getColorManagementConfig)
+        .doc() = R"docstring(
+    Class representing the top-level element in the MaterialX ownership
+    hierarchy.
+
+    :see: https://materialx.org/docs/api/class_document.html
+)docstring";
 }

source/PyMaterialX/PyMaterialXCore/PyElement.cpp

@@ -101,8 +101,11 @@ void bindPyElement(py::module& mod)
         .def("createValidChildName", &mx::Element::createValidChildName)
         .def("createStringResolver", &mx::Element::createStringResolver,
              py::arg("geom") = mx::EMPTY_STRING)
-        .def("asString", &mx::Element::asString)
+        .def("asString", &mx::Element::asString,
+             "Return a single-line description of this element, including its "
+             "category, name, and attributes.")
         .def("__str__", &mx::Element::asString)
+
         BIND_ELEMENT_FUNC_INSTANCE(Collection)
         BIND_ELEMENT_FUNC_INSTANCE(Document)
         BIND_ELEMENT_FUNC_INSTANCE(GeomInfo)
@@ -118,15 +121,29 @@ void bindPyElement(py::module& mod)
         BIND_ELEMENT_FUNC_INSTANCE(PropertySetAssign)
         BIND_ELEMENT_FUNC_INSTANCE(Token)
         BIND_ELEMENT_FUNC_INSTANCE(TypeDef)
-        BIND_ELEMENT_FUNC_INSTANCE(Visibility);
+        BIND_ELEMENT_FUNC_INSTANCE(Visibility)
+
+        .doc() = R"docstring(
+    Base class for MaterialX elements.
+
+    An `Element` is a named object within a `Document`, which may possess any
+    number of child elements and attributes.
+
+    :see: https://materialx.org/docs/api/class_element.html
+)docstring";
 
     py::class_<mx::TypedElement, mx::TypedElementPtr, mx::Element>(mod, "TypedElement")
         .def("setType", &mx::TypedElement::setType)
         .def("hasType", &mx::TypedElement::hasType)
         .def("getType", &mx::TypedElement::getType)
         .def("isMultiOutputType", &mx::TypedElement::isMultiOutputType)
         .def("getTypeDef", &mx::TypedElement::getTypeDef)
-        .def_readonly_static("TYPE_ATTRIBUTE", &mx::TypedElement::TYPE_ATTRIBUTE);
+        .def_readonly_static("TYPE_ATTRIBUTE", &mx::TypedElement::TYPE_ATTRIBUTE)
+        .doc() = R"docstring(
+    Base class for typed elements.
+
+    :see: https://materialx.org/docs/api/class_typed_element.html
+)docstring";
 
     py::class_<mx::ValueElement, mx::ValueElementPtr, mx::TypedElement>(mod, "ValueElement")
         .def("setValueString", &mx::ValueElement::setValueString)
@@ -181,19 +198,53 @@ void bindPyElement(py::module& mod)
         BIND_VALUE_ELEMENT_FUNC_INSTANCE(integerarray, mx::IntVec)
         BIND_VALUE_ELEMENT_FUNC_INSTANCE(booleanarray, mx::BoolVec)
         BIND_VALUE_ELEMENT_FUNC_INSTANCE(floatarray, mx::FloatVec)
-        BIND_VALUE_ELEMENT_FUNC_INSTANCE(stringarray, mx::StringVec);
+        BIND_VALUE_ELEMENT_FUNC_INSTANCE(stringarray, mx::StringVec)
+
+        .doc() = R"docstring(
+    Base class for elements that support typed values.
+
+    :see: https://materialx.org/docs/api/class_value_element.html
+)docstring";
 
     py::class_<mx::Token, mx::TokenPtr, mx::ValueElement>(mod, "Token")
-        .def_readonly_static("CATEGORY", &mx::Token::CATEGORY);
+        .def_readonly_static("CATEGORY", &mx::Token::CATEGORY)
+        .doc() = R"docstring(
+    A token element representing a string value.
+
+    Token elements are used to define input and output values for string
+    substitutions in image filenames.
+
+    :see: https://materialx.org/docs/api/class_token.html
+)docstring";
 
     py::class_<mx::CommentElement, mx::CommentElementPtr, mx::Element>(mod, "CommentElement")
-        .def_readonly_static("CATEGORY", &mx::CommentElement::CATEGORY);
+        .def_readonly_static("CATEGORY", &mx::CommentElement::CATEGORY)
+        .doc() = R"docstring(
+    Class representing a block of descriptive text within a `Document`,
+    which will be stored a comment when the document is written out.
+
+    The comment text may be accessed with the methods `Element.getDocString()`
+    and `Element.setDocString()`.
+
+    :see: https://materialx.org/docs/api/class_comment_element.html
+)docstring";
 
     py::class_<mx::NewlineElement, mx::NewlineElementPtr, mx::Element>(mod, "NewlineElement")
-        .def_readonly_static("CATEGORY", &mx::NewlineElement::CATEGORY);
+        .def_readonly_static("CATEGORY", &mx::NewlineElement::CATEGORY)
+        .doc() = R"docstring(
+    Class representing a newline within a `Document`.
+
+    :see: https://materialx.org/docs/api/class_newline_element.html
+)docstring";
 
     py::class_<mx::GenericElement, mx::GenericElementPtr, mx::Element>(mod, "GenericElement")
-        .def_readonly_static("CATEGORY", &mx::GenericElement::CATEGORY);
+        .def_readonly_static("CATEGORY", &mx::GenericElement::CATEGORY)
+        .doc() = R"docstring(
+    A generic element subclass, for instantiating elements with unrecognized
+    categories.
+
+    :see: https://materialx.org/docs/api/class_generic_element.html
+)docstring";
 
     py::class_<mx::StringResolver, mx::StringResolverPtr>(mod, "StringResolver")
         .def("setFilePrefix", &mx::StringResolver::setFilePrefix)
@@ -206,12 +257,51 @@ void bindPyElement(py::module& mod)
         .def("getFilenameSubstitutions", &mx::StringResolver::getFilenameSubstitutions)
         .def("setGeomNameSubstitution", &mx::StringResolver::setGeomNameSubstitution)
         .def("getGeomNameSubstitutions", &mx::StringResolver::getGeomNameSubstitutions)
-        .def("resolve", &mx::StringResolver::resolve);
+        .def("resolve", &mx::StringResolver::resolve)
+        .doc() = R"docstring(
+    A helper class for applying string modifiers to data values in the context
+    of a specific element and geometry.
+
+    A `StringResolver` may be constructed through the `Element.createStringResolver()`
+    method, which initializes it in the context of a specific `Element`, geometry,
+    and material.
+
+    Calling the `StringResolver.resolve()` method applies all modifiers to a
+    particular string value.
+
+    Methods such as `StringResolver.setFilePrefix()` may be used to edit the
+    stored string modifiers before calling `StringResolver.resolve()`.
+
+    :see: https://materialx.org/docs/api/class_string_resolver.html
+)docstring";
+
+    py::class_<mx::ElementPredicate>(mod, "ElementPredicate")
+        .doc() = R"docstring(
+    Class representing a function that takes an `Element` and returns a `bool`,
+    to check whether some criteria has passed.
+)docstring";
+
+    py::register_exception<mx::ExceptionOrphanedElement>(mod, "ExceptionOrphanedElement")
+        .doc() = R"docstring(
+    A type of exception that is raised when an `Element` is used after its owning
+    `Document` has gone out of scope.
 
-    py::class_<mx::ElementPredicate>(mod, "ElementPredicate");
+    :see: https://materialx.org/docs/api/class_exception_orphaned_element.html
+)docstring";
 
-    py::register_exception<mx::ExceptionOrphanedElement>(mod, "ExceptionOrphanedElement");
+    mod.def("targetStringsMatch", &mx::targetStringsMatch,
+            py::arg("target1"),
+            py::arg("target2"),
+            R"docstring(
+    Given two target strings, each containing a string array of target names,
+    return `True` if they have any targets in common.
 
-    mod.def("targetStringsMatch", &mx::targetStringsMatch);
-    mod.def("prettyPrint", &mx::prettyPrint);
+    An empty target string matches all targets.
+)docstring");
+    mod.def("prettyPrint", &mx::prettyPrint,
+            py::arg("element"),
+            R"docstring(
+    Pretty-print the given `element` tree, calling `Element.asString()`
+    recursively on each element in depth-first order.
+)docstring");
 }

source/PyMaterialX/PyMaterialXCore/PyException.cpp

@@ -13,6 +13,12 @@ namespace mx = MaterialX;
 void bindPyException(py::module& mod)
 {
     static py::exception<mx::Exception> pyException(mod, "Exception");
+    pyException.doc() = R"docstring(
+    The base class for exceptions that are propagated from the MaterialX library
+    to the client application.
+
+    :see: https://materialx.org/docs/api/class_exception.html
+)docstring";
 
     py::register_exception_translator(
         [](std::exception_ptr errPtr)