Extended docstrings of PyMaterialXCore and PyMaterialXFormat. (#1567

) Mentioning that all functions and classes from those modules are available in the top-level `MaterialX` Python package. Also removed the repeated `import` statements from example code in utility functions of `PyMaterialXCore`. Also wrapped more module docstrings in `PYMATERIALX_DOCSTRING()`. Signed-off-by: Stefan Habel <19556655+StefanHabel@users.noreply.github.com>
AcademySoftwareFoundation · Oct 31, 2023 · aed7f8f · aed7f8f
1 parent 37f1ef5
commit aed7f8f
Show file tree

Hide file tree

Showing 5 changed files with 22 additions and 19 deletions.
diff --git a/source/PyMaterialX/PyMaterialXCore/PyModule.cpp b/source/PyMaterialX/PyMaterialXCore/PyModule.cpp
@@ -29,6 +29,14 @@ PYBIND11_MODULE(PyMaterialXCore, mod)
     mod.doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Core MaterialX elements and graph traversal.
 
+    All functions and classes that are defined in this module are available in
+    the top-level `MaterialX` Python package, and are typically used via an
+    `import` alias named `mx`:
+
+    .. code:: python
+
+        import MaterialX as mx
+
     Library Version
     ---------------
 

diff --git a/source/PyMaterialX/PyMaterialXCore/PyUtil.cpp b/source/PyMaterialX/PyMaterialXCore/PyUtil.cpp
@@ -19,7 +19,6 @@ void bindPyUtil(py::module& mod)
             PYMATERIALX_DOCSTRING(R"docstring(
     Return the version of the MaterialX library as a string.
 
-    >>> import MaterialX as mx
     >>> mx.getVersionString()
     '1.38.9'
 
@@ -36,7 +35,6 @@ void bindPyUtil(py::module& mod)
     Return the major, minor, and build versions of the MaterialX library as an
     integer tuple.
 
-    >>> import MaterialX as mx
     >>> mx.getVersionIntegers()
     (1, 38, 9)
 )docstring"));
@@ -47,7 +45,6 @@ void bindPyUtil(py::module& mod)
     Create a valid MaterialX name from the given `name`,
     replacing invalid characters with the given `replaceChar`.
 
-    >>> import MaterialX as mx
     >>> mx.createValidName('left arm #123')
     'left_arm__123'
 )docstring"));
@@ -58,7 +55,6 @@ void bindPyUtil(py::module& mod)
     Return `True` if the given `name` is a valid MaterialX name,
     otherwise False.
 
-    >>> import MaterialX as mx
     >>> mx.isValidName('left arm #123')
     False
 )docstring"));
@@ -68,7 +64,6 @@ void bindPyUtil(py::module& mod)
             PYMATERIALX_DOCSTRING(R"docstring(
     Increment the numeric suffix of the given `name`.
 
-    >>> import MaterialX as mx
     >>> mx.incrementName('left arm #123')
     'left arm #124'
 )docstring"));
@@ -79,7 +74,6 @@ void bindPyUtil(py::module& mod)
     Split the given `string` into a list of substrings using the
     given set of separator characters.
 
-    >>> import MaterialX as mx
     >>> mx.splitString('MaterialX', 'aeiou')
     ['M', 't', 'r', 'lX']
 )docstring"));
@@ -90,7 +84,6 @@ void bindPyUtil(py::module& mod)
     Join a list of substrings into a single string, placing the
     given separator between each substring.
 
-    >>> import MaterialX as mx
     >>> mx.joinStrings(['M', 'teri', 'lX'], 'a')
     'MaterialX'
 )docstring"));
@@ -100,7 +93,6 @@ void bindPyUtil(py::module& mod)
             PYMATERIALX_DOCSTRING(R"docstring(
     Apply the given substring `substitutions` to the input `string`.
 
-    >>> import MaterialX as mx
     >>> mx.replaceSubstrings(
     ...     '/bob/alice/guido',
     ...     {'bob': 'b', 'alice': 'a', 'guido': 'g'}
@@ -114,7 +106,6 @@ void bindPyUtil(py::module& mod)
     Return `True` if the given `string` starts with the given `prefix`,
     otherwise `False`.
 
-    >>> import MaterialX as mx
     >>> mx.stringStartsWith('turbulence3d', 'turbulence')
     True
     >>> mx.stringStartsWith('turbulence3d', 'Turbulence')
@@ -127,7 +118,6 @@ void bindPyUtil(py::module& mod)
     Return `True` if the given `string` ends with the given `suffix`,
     otherwise `False`.
 
-    >>> import MaterialX as mx
     >>> mx.stringEndsWith('turbulence3d', '3d')
     True
     >>> mx.stringEndsWith('turbulence3d', '3D')
@@ -139,7 +129,6 @@ void bindPyUtil(py::module& mod)
             PYMATERIALX_DOCSTRING(R"docstring(
     Split the given `namePath` into a list of names.
 
-    >>> import MaterialX as mx
     >>> mx.splitNamePath('/robot2/right_arm')
     ['robot2', 'right_arm']
 )docstring"));
@@ -149,7 +138,6 @@ void bindPyUtil(py::module& mod)
             PYMATERIALX_DOCSTRING(R"docstring(
     Create a name path from the given list of `names`.
 
-    >>> import MaterialX as mx
     >>> mx.createNamePath(['robot2', 'right_arm'])
     'robot2/right_arm'
 )docstring"));
@@ -159,7 +147,6 @@ void bindPyUtil(py::module& mod)
             PYMATERIALX_DOCSTRING(R"docstring(
     Given a `namePath`, return the parent name path.
 
-    >>> import MaterialX as mx
     >>> mx.parentNamePath('/robot2/right_arm')
     'robot2'
 )docstring"));

diff --git a/source/PyMaterialX/PyMaterialXFormat/PyModule.cpp b/source/PyMaterialX/PyMaterialXFormat/PyModule.cpp
@@ -13,9 +13,17 @@ void bindPyUtil(py::module& mod);
 
 PYBIND11_MODULE(PyMaterialXFormat, mod)
 {
-    mod.doc() = R"docstring(
+    mod.doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Cross-platform support for file and search paths, and XML serialization.
 
+    All functions and classes that are defined in this module are available in
+    the top-level `MaterialX` Python package, and are typically used via an
+    `import` alias named `mx`:
+
+    .. code:: python
+
+        import MaterialX as mx
+
     File and Search Paths
     ---------------------
 
@@ -56,7 +64,7 @@ PYBIND11_MODULE(PyMaterialXFormat, mod)
         XmlWriteOptions
         ExceptionParseError
         ExceptionFileMissing
-)docstring";
+)docstring");
 
     // PyMaterialXFormat depends on types defined in PyMaterialXCore
     PYMATERIALX_IMPORT_MODULE(PyMaterialXCore);

diff --git a/source/PyMaterialX/PyMaterialXRender/PyModule.cpp b/source/PyMaterialX/PyMaterialXRender/PyModule.cpp
@@ -23,7 +23,7 @@ void bindPyCgltfLoader(py::module& mod);
 
 PYBIND11_MODULE(PyMaterialXRender, mod)
 {
-    mod.doc() = R"docstring(
+    mod.doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Core rendering support for MaterialX.
 
     Core Rendering Classes
@@ -85,7 +85,7 @@ PYBIND11_MODULE(PyMaterialXRender, mod)
         :toctree: exceptions
 
         ExceptionRenderError
-)docstring";
+)docstring");
 
     // PyMaterialXRender depends on types defined in PyMaterialXCore
     PYMATERIALX_IMPORT_MODULE(PyMaterialXCore);

diff --git a/source/PyMaterialX/PyMaterialXRenderGlsl/PyModule.cpp b/source/PyMaterialX/PyMaterialXRenderGlsl/PyModule.cpp
@@ -14,7 +14,7 @@ void bindPyTextureBaker(py::module& mod);
 
 PYBIND11_MODULE(PyMaterialXRenderGlsl, mod)
 {
-    mod.doc() = R"docstring(
+    mod.doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Rendering materials using OpenGL Shading Language.
 
     :see: https://www.opengl.org
@@ -31,7 +31,7 @@ PYBIND11_MODULE(PyMaterialXRenderGlsl, mod)
         GLTextureHandler
         Input
         TextureBaker
-)docstring";
+)docstring");
 
     // PyMaterialXRenderGlsl depends on types defined in PyMaterialXRender
     PYMATERIALX_IMPORT_MODULE(PyMaterialXRender);