Docstrings for PyMaterialXFormat classes.

Split from #1567. Update #342. Signed-off-by: Stefan Habel <[email protected]>
AcademySoftwareFoundation · Oct 13, 2024 · dcf76bc · dcf76bc
1 parent 0ba2ad0
commit dcf76bc
Show file tree

Hide file tree

Showing 2 changed files with 52 additions and 8 deletions.
diff --git a/source/PyMaterialX/PyMaterialXFormat/PyFile.cpp b/source/PyMaterialX/PyMaterialXFormat/PyFile.cpp
@@ -12,16 +12,33 @@ namespace mx = MaterialX;
 
 void bindPyFile(py::module& mod)
 {
-    py::enum_<mx::FilePath::Type>(mod, "Type")
-        .value("TypeRelative", mx::FilePath::Type::TypeRelative)
-        .value("TypeAbsolute", mx::FilePath::Type::TypeAbsolute)
-        .value("TypeNetwork", mx::FilePath::Type::TypeNetwork)
+    // Quirk: The `Type` enum is exposed at the module level, not as part of
+    // the `FilePath` class
+    py::enum_<mx::FilePath::Type>(mod, "Type", R"docstring(
+    Enumeration of `FilePath` types.
+
+    :see: https://materialx.org/docs/api/class_file_path.html#pub-types)docstring")
+        .value("TypeRelative", mx::FilePath::Type::TypeRelative,
+               "Type indicating a relative path, e.g. `'a/b'`. "
+               "This is the default file path type.")
+        .value("TypeAbsolute", mx::FilePath::Type::TypeAbsolute,
+               "Type indicating an absolute path, e.g. `'/a/b'`.")
+        .value("TypeNetwork", mx::FilePath::Type::TypeNetwork,
+               "Type indicating a network path on Windows, e.g. `'\\\\a\\b'`.")
         .export_values();
 
-    py::enum_<mx::FilePath::Format>(mod, "Format")
-        .value("FormatWindows", mx::FilePath::Format::FormatWindows)
-        .value("FormatPosix", mx::FilePath::Format::FormatPosix)
-        .value("FormatNative", mx::FilePath::Format::FormatNative)
+    // Quirk: The `Format` enum is exposed at the module level, not as part of
+    // the `FilePath` class
+    py::enum_<mx::FilePath::Format>(mod, "Format", R"docstring(
+    Enumeration of `FilePath` formats.
+
+    :see: https://materialx.org/docs/api/class_file_path.html#pub-types)docstring")
+        .value("FormatWindows", mx::FilePath::Format::FormatWindows,
+               "Format indicating a Windows environment.")
+        .value("FormatPosix", mx::FilePath::Format::FormatPosix,
+               "Format indicating a Linux or Mac environment.")
+        .value("FormatNative", mx::FilePath::Format::FormatNative,
+               "Format indicating the format used on the system for which the library was built.")
         .export_values();
 
     py::class_<mx::FilePath>(mod, "FilePath")
@@ -48,6 +65,10 @@ void bindPyFile(py::module& mod)
         .def("createDirectory", &mx::FilePath::createDirectory)
         .def_static("getCurrentPath", &mx::FilePath::getCurrentPath)
         .def_static("getModulePath", &mx::FilePath::getModulePath);
+    mod.attr("FilePath").doc() = R"docstring(
+    A generic file path, supporting both syntactic and file system operations.
+
+    :see: https://materialx.org/docs/api/class_file_path.html)docstring";
 
     py::class_<mx::FileSearchPath>(mod, "FileSearchPath")
         .def(py::init<>())
@@ -62,6 +83,11 @@ void bindPyFile(py::module& mod)
         .def("size", &mx::FileSearchPath::size)
         .def("isEmpty", &mx::FileSearchPath::isEmpty)
         .def("find", &mx::FileSearchPath::find);
+    mod.attr("FileSearchPath").doc() = R"docstring(
+    A sequence of file paths, which may be queried to find the first instance
+    of a given filename on the file system.
+
+    :see: https://materialx.org/docs/api/class_file_search_path.html)docstring";
 
     py::implicitly_convertible<std::string, mx::FilePath>();
     py::implicitly_convertible<std::string, mx::FileSearchPath>();

diff --git a/source/PyMaterialX/PyMaterialXFormat/PyXmlIo.cpp b/source/PyMaterialX/PyMaterialXFormat/PyXmlIo.cpp
@@ -20,11 +20,19 @@ void bindPyXmlIo(py::module& mod)
         .def_readwrite("readNewlines", &mx::XmlReadOptions::readNewlines)
         .def_readwrite("upgradeVersion", &mx::XmlReadOptions::upgradeVersion)        
         .def_readwrite("parentXIncludes", &mx::XmlReadOptions::parentXIncludes);
+    mod.attr("XmlReadOptions").doc() = R"docstring(
+    A set of options for controlling the behavior of XML read functions.
+
+    :see: https://materialx.org/docs/api/class_xml_read_options.html)docstring";
 
     py::class_<mx::XmlWriteOptions>(mod, "XmlWriteOptions")
         .def(py::init())
         .def_readwrite("writeXIncludeEnable", &mx::XmlWriteOptions::writeXIncludeEnable)
         .def_readwrite("elementPredicate", &mx::XmlWriteOptions::elementPredicate);
+    mod.attr("XmlWriteOptions").doc() = R"docstring(
+    A set of options for controlling the behavior of XML write functions.
+
+    :see: https://materialx.org/docs/api/class_xml_write_options.html)docstring";
 
     mod.def("readFromXmlFileBase", &mx::readFromXmlFile,
         py::arg("doc"), py::arg("filename"), py::arg("searchPath") = mx::FileSearchPath(), py::arg("readOptions") = (mx::XmlReadOptions*) nullptr);
@@ -43,5 +51,15 @@ void bindPyXmlIo(py::module& mod)
     mod.attr("MATERIALX_SEARCH_PATH_ENV_VAR") = mx::MATERIALX_SEARCH_PATH_ENV_VAR;
 
     py::register_exception<mx::ExceptionParseError>(mod, "ExceptionParseError");
+    mod.attr("ExceptionParseError").doc() = R"docstring(
+    A type of exception that is raised when a requested document cannot be
+    parsed.
+
+    :see: https://materialx.org/docs/api/class_exception_parse_error.html)docstring";
+
     py::register_exception<mx::ExceptionFileMissing>(mod, "ExceptionFileMissing");
+    mod.attr("ExceptionFileMissing").doc() = R"docstring(
+    A type of exception that is raised when a requested file cannot be opened.
+
+    :see: https://materialx.org/docs/api/class_exception_file_missing.html)docstring";
 }