Sphinx Python Documentation (#1567) - Resolved import order dependenc…

…y issue.

This patch adds calls of `pybind11::module::import()` to the Python
bindings of modules that depend on specific other modules.

This approach is similar to importing required modules via `import` in
Python packages/modules.

At the same time, we can remove the new documentation for this issue,
and can remove extra steps from the Sphinx `conf.py` configuration file.

With this patch in place, it should be possible to import any of the
MaterialX Python modules in any order.

documents/DeveloperGuide/index.rst

@@ -46,26 +46,3 @@ MaterialX Python Modules
     PyMaterialXRenderGlsl
     PyMaterialXRenderOsl
     PyMaterialXRenderMsl
-
-
-Import Order Dependencies
--------------------------
-
-Note that the order in which the MaterialX Python modules are imported matters, as there are dependencies between them:
-
-- :py:mod:`PyMaterialXCore` -- typically always needed
-    - :py:mod:`PyMaterialXFormat` -- needed for file I/O
-    - :py:mod:`PyMaterialXRender` -- needed for core rendering
-        - :py:mod:`PyMaterialXRenderGlsl` -- render using OpenGL Shading Language
-        - :py:mod:`PyMaterialXRenderMsl` -- render using Metal Shading Language
-        - :py:mod:`PyMaterialXRenderOsl` -- render using Open Shading Language
-- :py:mod:`PyMaterialXGenShader` -- needed for core shader generation
-    - :py:mod:`PyMaterialXGenGlsl` -- generating shaders using OpenGL Shading Language
-    - :py:mod:`PyMaterialXGenMdl` -- generating shaders using Material Definition Language
-    - :py:mod:`PyMaterialXGenMsl` -- generating shaders using Metal Shading Language
-    - :py:mod:`PyMaterialXGenOsl` -- generating shaders using Open Shading Language
-
-That is to say, for example:
-
-- :py:mod:`PyMaterialXCore` needs to be imported before :py:mod:`PyMaterialXFormat` and :py:mod:`PyMaterialXRender`
-- :py:mod:`PyMaterialXGenShader` needs to be imported before :py:mod:`PyMaterialXGenMsl`

documents/sphinx-conf.py.in

@@ -19,36 +19,6 @@ import sys
 sys.path.insert(0, os.path.abspath('${MATERIALX_PYTHONPATH}'))
 
 
-# -- Module Import Order Dependencies ----------------------------------------
-
-# Make sure to import the core module before modules like `PyMaterialXFormat`
-# and `PyMaterialXRender`, as otherwise, their import fails with an
-# `ImportError` exception:
-# ```
-# ImportError: arg(): could not convert default argument into a Python object
-# (type not registered yet?).
-# ```
-import PyMaterialXCore
-
-# Make sure to import `PyMaterialXRender` before modules like
-# `PyMaterialXRenderMsl`, as otherwise, their import fails with an
-# `ImportError` exception, for example:
-# ```
-# ImportError: generic_type: type "MslRenderer" referenced unknown base type
-# "MaterialX_v1_38_9::ShaderRenderer"
-# ```
-import PyMaterialXRender
-
-# Make sure to import `PyMaterialXGenShader` before modules like
-# `PyMaterialXGenGlsl`, as otherwise, their import fails with an `ImportError`
-# exception, for example:
-# ```
-# ImportError: generic_type: type "GlslShaderGenerator" referenced unknown base
-# type "MaterialX_v1_38_9::HwShaderGenerator"
-# ```
-import PyMaterialXGenShader
-
-
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 

source/PyMaterialX/PyMaterialXFormat/PyModule.cpp

@@ -15,6 +15,9 @@ PYBIND11_MODULE(PyMaterialXFormat, mod)
 {
     mod.doc() = "Cross-platform support for working with files, paths, and environment variables";
 
+    // PyMaterialXFormat depends on types defined in PyMaterialXCore
+    pybind11::module::import("PyMaterialXCore");
+
     bindPyFile(mod);
     bindPyXmlIo(mod);
     bindPyUtil(mod);

source/PyMaterialX/PyMaterialXGenGlsl/PyModule.cpp

@@ -16,6 +16,9 @@ PYBIND11_MODULE(PyMaterialXGenGlsl, mod)
 {
     mod.doc() = "Shader generation using OpenGL Shading Language";
 
+    // PyMaterialXGenGlsl depends on types defined in PyMaterialXGenShader
+    pybind11::module::import("PyMaterialXGenShader");
+
     bindPyGlslShaderGenerator(mod);
     bindPyGlslResourceBindingContext(mod);
 

source/PyMaterialX/PyMaterialXGenMdl/PyModule.cpp

@@ -13,5 +13,8 @@ PYBIND11_MODULE(PyMaterialXGenMdl, mod)
 {
     mod.doc() = "Shader generation using Material Definition Language";
 
+    // PyMaterialXGenMdl depends on types defined in PyMaterialXGenShader
+    pybind11::module::import("PyMaterialXGenShader");
+
     bindPyMdlShaderGenerator(mod);
 };

source/PyMaterialX/PyMaterialXGenMsl/PyModule.cpp

@@ -14,6 +14,9 @@ PYBIND11_MODULE(PyMaterialXGenMsl, mod)
 {
     mod.doc() = "Shader generation using Metal Shading Language";
 
+    // PyMaterialXGenMsl depends on types defined in PyMaterialXGenShader
+    pybind11::module::import("PyMaterialXGenShader");
+
     bindPyMslShaderGenerator(mod);
     bindPyMslResourceBindingContext(mod);
 }

source/PyMaterialX/PyMaterialXGenOsl/PyModule.cpp

@@ -13,5 +13,8 @@ PYBIND11_MODULE(PyMaterialXGenOsl, mod)
 {
     mod.doc() = "Shader generation using Open Shading Language";
 
+    // PyMaterialXGenOsl depends on types defined in PyMaterialXGenShader
+    pybind11::module::import("PyMaterialXGenShader");
+
     bindPyOslShaderGenerator(mod);
 }

source/PyMaterialX/PyMaterialXRender/PyModule.cpp

@@ -25,6 +25,9 @@ PYBIND11_MODULE(PyMaterialXRender, mod)
 {
     mod.doc() = "Core rendering functionality for MaterialX";
 
+    // PyMaterialXRender depends on types defined in PyMaterialXCore
+    pybind11::module::import("PyMaterialXCore");
+
     bindPyMesh(mod);
     bindPyGeometryHandler(mod);
     bindPyLightHandler(mod);

source/PyMaterialX/PyMaterialXRenderGlsl/PyModule.cpp

@@ -16,6 +16,9 @@ PYBIND11_MODULE(PyMaterialXRenderGlsl, mod)
 {
     mod.doc() = "Rendering materials using OpenGL Shading Language";
 
+    // PyMaterialXRenderGlsl depends on types defined in PyMaterialXRender
+    pybind11::module::import("PyMaterialXRender");
+
     bindPyGlslProgram(mod);
     bindPyGlslRenderer(mod);
     bindPyGLTextureHandler(mod);

source/PyMaterialX/PyMaterialXRenderMsl/PyModule.mm

@@ -16,6 +16,9 @@
 {
     mod.doc() = "Rendering materials using Metal Shading Language";
 
+    // PyMaterialXRenderMsl depends on types defined in PyMaterialXRender
+    pybind11::module::import("PyMaterialXRender");
+
     bindPyMslProgram(mod);
     bindPyMslRenderer(mod);
     bindPyMetalTextureHandler(mod);

source/PyMaterialX/PyMaterialXRenderOsl/PyModule.cpp

@@ -13,5 +13,8 @@ PYBIND11_MODULE(PyMaterialXRenderOsl, mod)
 {
     mod.doc() = "Rendering materials using Open Shading Language";
 
+    // PyMaterialXRenderOsl depends on types defined in PyMaterialXRender
+    pybind11::module::import("PyMaterialXRender");
+
     bindPyOslRenderer(mod);
 }