Work in progress.

This PR adds a new build target named `MaterialXDocsPython`,
which generates Python API documentation using Sphinx.

The existing developer guide contents are incorporated into
the new HTML documentation, which lives side-by-side to the
existing Doxygen-generated C++ API documentation.

The docstrings of the Python modules were tweaked to describe
what the individual modules are responsible for.

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

…MATERIALX_BUILD_PYTHON_DOCS build option.

…d Markdown files to use absolute URLs.

This is to make sure the URLs can be loaded within GitHub, Doxygen,
Sphinx, and the PyPI project page. Requires internet access.

Also updated XML text snippets to use XML comment delimiters.

…d `index.rst`.

Changed index page title, added introduction text, and changed the
order of Python modules, to reflect the order in which support for the
different shading languages was added to MaterialX.

…ed import order dependency 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.

…d Sphinx configuration.

- Added a new description/about text in the sidebar, including blue
  link buttons to GitHub and MaterialX on Mastodon (with an SVG-based
  embedded icon)
- Applied the "monokai" syntax highlighting theme to code snippets
- Added custom Jinja templates for classes and modules, in order to add
  a section title before the alphabetical indices on pages
- Added a custom HTML template for the navigation section in the sidebar
  in order to limit the depth of the table of contents
- Added code to remove module names from the signatures of functions,
  in order to make the docs more readable

…a couple of typos in header files.

…define to produce detailed error messages in pybind11.

…docstrings to PyMaterialXCore.

…docstrings to PyMaterialXFormat.

…docstrings to PyMaterialXGenGlsl.

…docstrings to PyMaterialXGenMdl.

…docstrings to PyMaterialXGenMsl.

…docstrings to PyMaterialXGenOsl.

…docstrings to PyMaterialXGenShader.

…docstrings to PyMaterialXRender.

…docstrings to PyMaterialXRenderGlsl.

…docstrings to PyMaterialXRenderMsl.

…docstrings to PyMaterialXRenderOsl.

…d listings of modules in `README.md` files.

…d aliasing of `PyMaterialXFormat.readFromXmlFile()` function.

The function is now exposed under its real name in the pybind11 bindings
in C++.

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

either within the `MaterialX` Python package or as a standalone module.

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

from docstrings.

This allows us to start docstrings on a new line, while keeping the help
text that `help()` in a `python` session provides clean.

Also added docstrings to a couple more functions.

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

The warnings give us an idea of how much work is left to be done:
```
The MaterialX Python API consists of:
    * 11 modules
    * 48 functions
    * 139 classes
    * 1176 methods
    * 6 exception types

WARNING: 475 methods look like their parameters have not all been named using `py::arg()`:
```

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

…undation#1567)

...to mention the `MaterialX` Python package, and the way it's typically
aliased as `mx` upon `import`.

Also removed the paragraph about the MaterialX.org site, as it seemed
unnecessary.

Also added a link to the auto-generated alphabetical index to the TOC.

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

…oftwareFoundation#1567)

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

…s. (AcademySoftwareFoundation#1567)

For example:
```
WARNING: 1141 methods look like they do not have docstrings yet.
```

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

…mySoftwareFoundation#1567)

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

…oundation#1567)

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

…emySoftwareFoundation#1567)

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

…Documentation

Signed-off-by: Jonathan Stone <[email protected]>

…ademySoftwareFoundation#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 <[email protected]>

…areFoundation#1567)

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

…wareFoundation#1567)

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

…Foundation#1567)

...by renaming `Element._getChild()` to `Element.getChild()`.

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

…on#1567)

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

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

AcademySoftwareFoundation#1567)

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

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

…ation#1567)

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

…cademySoftwareFoundation#1567)

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

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

…c-process-bases'. (AcademySoftwareFoundation#1567)

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

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

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

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

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

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

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

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

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

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

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

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