Adding docstrings for PyMaterialXGen*.

This PR adds docstrings in markdown format to the following modules:
- `PyMaterialXGenGlsl`
- `PyMaterialXGenMdl`
- `PyMaterialXGenMsl`
- `PyMaterialXGenOsl`
- `PyMaterialXGenShader`

The docstrings are defined in macros named `PyMaterialXGen*_DOCSTRING` that
use the new `PYMATERIALX_DOCSTRING` macro that is introduced in AcademySoftwareFoundation#2038 to
allow us to place the first and last lines in lines by themselves, rather
than starting the docstring contents immediately after the `R"docstring(`
marker.

The `PyMaterialXGen*_DOCSTRING` macros are placed in separate header files
named `__doc__.md.h` which live side-by-side with their corresponding
`PyModule.cpp` file in which it is included.

Note that the docstrings for individual classes, methods, and functions are
to be added in separate PRs.

Split from AcademySoftwareFoundation#1567.

Depends on AcademySoftwareFoundation#2038.

Update AcademySoftwareFoundation#342.

Signed-off-by: Stefan Habel <[email protected]>

source/PyMaterialX/PyMaterialXGenGlsl/PyModule.cpp

@@ -4,6 +4,7 @@
 //
 
 #include <PyMaterialX/PyMaterialX.h>
+#include "__doc__.md.h"
 
 namespace py = pybind11;
 
@@ -14,7 +15,7 @@ void bindPyVkShaderGenerator(py::module& mod);
 
 PYBIND11_MODULE(PyMaterialXGenGlsl, mod)
 {
-    mod.doc() = "Module containing Python bindings for the MaterialXGenGlsl library";
+    mod.doc() = PyMaterialXGenGlsl_DOCSTRING;
 
     // PyMaterialXGenGlsl depends on types defined in PyMaterialXGenShader
     PYMATERIALX_IMPORT_MODULE(PyMaterialXGenShader);

source/PyMaterialX/PyMaterialXGenGlsl/__doc__.md.h

@@ -0,0 +1,37 @@
+//
+// Copyright Contributors to the MaterialX Project
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Docstring for the PyMaterialXGenGlsl module
+
+#define PyMaterialXGenGlsl_DOCSTRING PYMATERIALX_DOCSTRING(R"docstring(
+Shader generation using the OpenGL Shading Language.
+
+:see: https://www.opengl.org
+:see: https://www.vulkan.org
+
+GLSL Shader Generation Classes
+------------------------------
+
+**Class Hierarchy**
+
+* `PyMaterialXGenShader.ShaderGenerator`
+    * `PyMaterialXGenShader.HwShaderGenerator`
+        * `GlslShaderGenerator`
+            * `EsslShaderGenerator`
+            * `VkShaderGenerator`
+* `PyMaterialXGenShader.GenUserData`
+    * `PyMaterialXGenShader.HwResourceBindingContext`
+        * `GlslResourceBindingContext`
+
+**Class Index**
+
+.. autosummary::
+    :toctree: glsl-shader-generators
+
+    GlslShaderGenerator
+    EsslShaderGenerator
+    VkShaderGenerator
+    GlslResourceBindingContext
+)docstring");

source/PyMaterialX/PyMaterialXGenMdl/PyModule.cpp

@@ -4,14 +4,15 @@
 //
 
 #include <PyMaterialX/PyMaterialX.h>
+#include "__doc__.md.h"
 
 namespace py = pybind11;
 
 void bindPyMdlShaderGenerator(py::module& mod);
 
 PYBIND11_MODULE(PyMaterialXGenMdl, mod)
 {
-    mod.doc() = "Module containing Python bindings for the MaterialXGenMdl library";
+    mod.doc() = PyMaterialXGenMdl_DOCSTRING;
 
     // PyMaterialXGenMdl depends on types defined in PyMaterialXGenShader
     PYMATERIALX_IMPORT_MODULE(PyMaterialXGenShader);

source/PyMaterialX/PyMaterialXGenMdl/__doc__.md.h

@@ -0,0 +1,28 @@
+//
+// Copyright Contributors to the MaterialX Project
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Docstring for the PyMaterialXGenMdl module
+
+#define PyMaterialXGenMdl_DOCSTRING PYMATERIALX_DOCSTRING(R"docstring(
+Shader generation using the Material Definition Language.
+
+:see: https://www.nvidia.com/en-us/design-visualization/technologies/material-definition-language/
+:see: https://raytracing-docs.nvidia.com/mdl/index.html
+
+MDL Shader Generation Classes
+-----------------------------
+
+**Class Hierarchy**
+
+* `PyMaterialXGenShader.ShaderGenerator`
+    * `MdlShaderGenerator`
+
+**Class Index**
+
+.. autosummary::
+    :toctree: mdl-shader-generators
+
+    MdlShaderGenerator
+)docstring");

source/PyMaterialX/PyMaterialXGenMsl/PyModule.cpp

@@ -4,6 +4,7 @@
 //
 
 #include <PyMaterialX/PyMaterialX.h>
+#include "__doc__.md.h"
 
 namespace py = pybind11;
 
@@ -12,7 +13,7 @@ void bindPyMslResourceBindingContext(py::module &mod);
 
 PYBIND11_MODULE(PyMaterialXGenMsl, mod)
 {
-    mod.doc() = "Module containing Python bindings for the MaterialXGenMsl library";
+    mod.doc() = PyMaterialXGenMsl_DOCSTRING;
 
     // PyMaterialXGenMsl depends on types defined in PyMaterialXGenShader
     PYMATERIALX_IMPORT_MODULE(PyMaterialXGenShader);

source/PyMaterialX/PyMaterialXGenMsl/__doc__.md.h

@@ -0,0 +1,33 @@
+//
+// Copyright Contributors to the MaterialX Project
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Docstring for the PyMaterialXGenMsl module
+
+#define PyMaterialXGenMsl_DOCSTRING PYMATERIALX_DOCSTRING(R"docstring(
+Shader generation using the Metal Shading Language.
+
+:see: https://developer.apple.com/metal/
+:see: https://developer.apple.com/documentation/metal
+
+MSL Shader Generation Classes
+-----------------------------
+
+**Class Hierarchy**
+
+* `PyMaterialXGenShader.ShaderGenerator`
+    * `PyMaterialXGenShader.HwShaderGenerator`
+        * `MslShaderGenerator`
+* `PyMaterialXGenShader.GenUserData`
+    * `PyMaterialXGenShader.HwResourceBindingContext`
+        * `MslResourceBindingContext`
+
+**Class Index**
+
+.. autosummary::
+    :toctree: msl-shader-generators
+
+    MslShaderGenerator
+    MslResourceBindingContext
+)docstring");

source/PyMaterialX/PyMaterialXGenOsl/PyModule.cpp

@@ -4,14 +4,15 @@
 //
 
 #include <PyMaterialX/PyMaterialX.h>
+#include "__doc__.md.h"
 
 namespace py = pybind11;
 
 void bindPyOslShaderGenerator(py::module& mod);
 
 PYBIND11_MODULE(PyMaterialXGenOsl, mod)
 {
-    mod.doc() = "Module containing Python bindings for the MaterialXGenOsl library";
+    mod.doc() = PyMaterialXGenOsl_DOCSTRING;
 
     // PyMaterialXGenOsl depends on types defined in PyMaterialXGenShader
     PYMATERIALX_IMPORT_MODULE(PyMaterialXGenShader);

source/PyMaterialX/PyMaterialXGenOsl/__doc__.md.h

@@ -0,0 +1,28 @@
+//
+// Copyright Contributors to the MaterialX Project
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Docstring for the PyMaterialXGenOsl module
+
+#define PyMaterialXGenOsl_DOCSTRING PYMATERIALX_DOCSTRING(R"docstring(
+Shader generation using the Open Shading Language.
+
+:see: https://openshadinglanguage.org/
+:see: https://open-shading-language.readthedocs.io/
+
+OSL Shader Generation Classes
+-----------------------------
+
+**Class Hierarchy**
+
+* `PyMaterialXGenShader.ShaderGenerator`
+    * `OslShaderGenerator`
+
+**Class Index**
+
+.. autosummary::
+    :toctree: osl-shader-generators
+
+    OslShaderGenerator
+)docstring");

source/PyMaterialX/PyMaterialXGenShader/PyModule.cpp

@@ -4,6 +4,7 @@
 //
 
 #include <PyMaterialX/PyMaterialX.h>
+#include "__doc__.md.h"
 
 namespace py = pybind11;
 
@@ -24,7 +25,7 @@ void bindPyUnitSystem(py::module& mod);
 
 PYBIND11_MODULE(PyMaterialXGenShader, mod)
 {
-    mod.doc() = "Module containing Python bindings for the MaterialXGenShader library";
+    mod.doc() = PyMaterialXGenShader_DOCSTRING;
 
     bindPyColorManagement(mod);
     bindPyShaderPort(mod);

source/PyMaterialX/PyMaterialXGenShader/__doc__.md.h

@@ -0,0 +1,75 @@
+//
+// Copyright Contributors to the MaterialX Project
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Docstring for the PyMaterialXGenShader module
+
+#define PyMaterialXGenShader_DOCSTRING PYMATERIALX_DOCSTRING(R"docstring(
+Core shader generation support.
+
+Shader Generation Classes
+-------------------------
+
+.. autosummary::
+    :toctree: shader-generation
+
+    ShaderGenerator
+    HwShaderGenerator
+    HwResourceBindingContext
+    GenContext
+    GenOptions
+    GenUserData
+    ApplicationVariableHandler
+    Shader
+    ShaderPort
+    ShaderPortPredicate
+    ShaderStage
+    ShaderTranslator
+    TypeDesc
+    VariableBlock
+
+Enumeration Classes
+-------------------
+
+.. autosummary::
+    :toctree: enumeration
+
+    ShaderInterfaceType
+    HwSpecularEnvironmentMethod
+
+Color Management Classes
+------------------------
+
+.. autosummary::
+    :toctree: color-management
+
+    ColorManagementSystem
+    DefaultColorManagementSystem
+    ColorSpaceTransform
+
+Unit System Classes
+-------------------
+
+.. autosummary::
+    :toctree: unit-system
+
+    UnitSystem
+    UnitTransform
+
+Utility Functions
+-----------------
+
+.. autofunction:: connectsToWorldSpaceNode
+.. autofunction:: elementRequiresShading
+.. autofunction:: findRenderableElements
+.. autofunction:: findRenderableMaterialNodes
+.. autofunction:: getNodeDefInput
+.. autofunction:: getUdimCoordinates
+.. autofunction:: getUdimScaleAndOffset
+.. autofunction:: hasElementAttributes
+.. autofunction:: isTransparentSurface
+.. autofunction:: mapValueToColor
+.. autofunction:: requiresImplementation
+.. autofunction:: tokenSubstitution
+)docstring");