Adding docstrings for PyMaterialXRender*.

This PR adds docstrings in markdown format to the following modules:
- `PyMaterialXRender`
- `PyMaterialXRenderGlsl`
- `PyMaterialXRenderMsl`
- `PyMaterialXRenderOsl`

The docstrings are defined in macros named `PyMaterialXRender*_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 `PyMaterialXRender*_DOCSTRING` macros are placed in separate header
files named `__doc__.md.h` which live side-by-side with their corresponding
`PyModule.cpp` files in which they are 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/PyMaterialXRender/PyModule.cpp

@@ -4,6 +4,7 @@
 //
 
 #include <PyMaterialX/PyMaterialX.h>
+#include "__doc__.md.h"
 
 namespace py = pybind11;
 
@@ -23,7 +24,7 @@ void bindPyCgltfLoader(py::module& mod);
 
 PYBIND11_MODULE(PyMaterialXRender, mod)
 {
-    mod.doc() = "Module containing Python bindings for the MaterialXRender library";
+    mod.doc() = PyMaterialXRender_DOCSTRING;
 
     // PyMaterialXRender depends on types defined in PyMaterialXCore
     PYMATERIALX_IMPORT_MODULE(PyMaterialXCore);

source/PyMaterialX/PyMaterialXRender/__doc__.md.h

@@ -0,0 +1,70 @@
+//
+// Copyright Contributors to the MaterialX Project
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Docstring for the PyMaterialXRender module
+
+#define PyMaterialXRender_DOCSTRING PYMATERIALX_DOCSTRING(R"docstring(
+Core rendering support for MaterialX.
+
+Core Rendering Classes
+----------------------
+
+.. autosummary::
+    :toctree: core-rendering
+
+    ShaderRenderer
+    Camera
+    LightHandler
+
+Geometry Classes
+----------------
+
+.. autosummary::
+    :toctree: geometry
+
+    GeometryHandler
+    GeometryLoader
+    CgltfLoader
+    TinyObjLoader
+    Mesh
+    MeshPartition
+    MeshStream
+
+Image Classes
+--------------
+
+.. autosummary::
+    :toctree: images
+
+    ImageHandler
+    ImageLoader
+    StbImageLoader
+    Image
+    ImageBufferDeallocator
+    ImageSamplingProperties
+
+Image Functions
+---------------
+
+.. autofunction:: createImageStrip
+.. autofunction:: createUniformImage
+.. autofunction:: getMaxDimensions
+
+Enumeration Classes
+-------------------
+
+.. autosummary::
+    :toctree: enumerations
+
+    BaseType
+
+Exception Classes
+-----------------
+
+.. autosummary::
+    :toctree: exceptions
+
+    ExceptionRenderError
+)docstring");

source/PyMaterialX/PyMaterialXRenderGlsl/PyModule.cpp

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

source/PyMaterialX/PyMaterialXRenderGlsl/__doc__.md.h

@@ -0,0 +1,35 @@
+//
+// Copyright Contributors to the MaterialX Project
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Docstring for the PyMaterialXRenderGlsl module
+
+#define PyMaterialXRenderGlsl_DOCSTRING PYMATERIALX_DOCSTRING(R"docstring(
+Rendering materials using the OpenGL Shading Language.
+
+:see: https://www.opengl.org
+:see: https://www.vulkan.org
+
+GLSL Rendering Classes
+----------------------
+
+**Class Hierarchy**
+
+* `PyMaterialXRender.ShaderRenderer`
+    * `GlslRenderer`
+        * `TextureBaker`
+* `PyMaterialXRender.ImageHandler`
+    * `GLTextureHandler`
+
+**Class Index**
+
+.. autosummary::
+    :toctree: glsl-rendering
+
+    GlslRenderer
+    GlslProgram
+    GLTextureHandler
+    Input
+    TextureBaker
+)docstring");

source/PyMaterialX/PyMaterialXRenderMsl/PyModule.mm

@@ -4,6 +4,7 @@
 //
 
 #include <PyMaterialX/PyMaterialX.h>
+#include "__doc__.md.h"
 
 namespace py = pybind11;
 
@@ -14,7 +15,7 @@
 
 PYBIND11_MODULE(PyMaterialXRenderMsl, mod)
 {
-    mod.doc() = "Module containing Python bindings for the MaterialXRenderMsl library";
+    mod.doc() = PyMaterialXRenderMsl_DOCSTRING;
 
     // PyMaterialXRenderMsl depends on types defined in PyMaterialXRender
     PYMATERIALX_IMPORT_MODULE(PyMaterialXRender);

source/PyMaterialX/PyMaterialXRenderMsl/__doc__.md.h

@@ -0,0 +1,35 @@
+//
+// Copyright Contributors to the MaterialX Project
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Docstring for the PyMaterialXRenderMsl module
+
+#define PyMaterialXRenderMsl_DOCSTRING PYMATERIALX_DOCSTRING(R"docstring(
+Rendering materials using the Metal Shading Language.
+
+:see: https://developer.apple.com/metal/
+:see: https://developer.apple.com/documentation/metal
+
+Metal Rendering Classes
+-----------------------
+
+**Class Hierarchy**
+
+* `PyMaterialXRender.ShaderRenderer`
+    * `MslRenderer`
+        * `TextureBaker`
+* `PyMaterialXRender.ImageHandler`
+    * `MetalTextureHandler`
+
+**Class Index**
+
+.. autosummary::
+    :toctree: metal-rendering
+
+    MslRenderer
+    MslProgram
+    MetalTextureHandler
+    Input
+    TextureBaker
+)docstring");

source/PyMaterialX/PyMaterialXRenderOsl/PyModule.cpp

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

source/PyMaterialX/PyMaterialXRenderOsl/__doc__.md.h

@@ -0,0 +1,28 @@
+//
+// Copyright Contributors to the MaterialX Project
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Docstring for the PyMaterialXRenderOsl module
+
+#define PyMaterialXRenderOsl_DOCSTRING PYMATERIALX_DOCSTRING(R"docstring(
+Rendering materials using the Open Shading Language.
+
+:see: https://openshadinglanguage.org/
+:see: https://open-shading-language.readthedocs.io/
+
+OSL Rendering Classes
+---------------------
+
+**Class Hierarchy**
+
+* `PyMaterialXRender.ShaderRenderer`
+    * `OslRenderer`
+
+**Class Index**
+
+.. autosummary::
+    :toctree: osl-rendering
+
+    OslRenderer
+)docstring");