Sphinx Python Documentation

[StefanHabel]

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.

Docstrings were added to all modules, functions, classes, methods, and attributes.

All parameters were named. None should appear as arg0, arg1, arg2 etc anymore.

Statistics about the Python API have been added to the Sphinx build process.

The Sphinx build output currently ends with the following messages, providing an overview of the state of the API docs:

The MaterialX Python API consists of:
    * 11 modules
    * 48 functions
    * 139 classes
    * 1180 methods
    * 6 exception types

build succeeded.

Docstring example:

$ python3 -c 'import PyMaterialXFormat; help(PyMaterialXFormat.flattenFilenames)'

Help on built-in function flattenFilenames in module PyMaterialXFormat:

flattenFilenames(...) method of builtins.PyCapsule instance
    flattenFilenames(doc: PyMaterialXCore.Document, searchPath: PyMaterialXFormat.FileSearchPath = mx.FileSearchPath(), customResolver: PyMaterialXCore.StringResolver = None) -> None

    Flatten all filenames in the given document, applying string resolvers at
    the scope of each element and removing all fileprefix attributes.

    :param doc: The document to modify.
    :type doc: Document
    :param searchPath: An optional search path for relative to absolute path
        conversion.
    :type searchPath: FileSearchPath
    :param customResolver: An optional custom resolver to apply.
    :type customResolver: StringResolver

Preview of generated HTML pages:

---

---

Development environment:

• Apple clang version 15.0.0 (clang-1500.0.40.1)
• Python 3.12.0 (v3.12.0:0fb18b02c8, Oct 2 2023, 09:45:56) [Clang 13.0.0 (clang-1300.0.29.30)] on darwin
• Sphinx 7.2.6
• cmake version 3.27.6

Update #342

[linux-foundation-easycla[bot]]

The committers listed above are authorized under a signed CLA.

• :white_check_mark: login: StefanHabel / name: Stefan Habel (bef6e1fb478400d5a7a95c673a51f4a9d777c8d4, 9d4b4929c8bcf5f647692f078e44e7956949ab18, e129d65ee2ba3d3acb9996c131da61c78731d165, 6a5da31928a817691f7fa44b7722dccf9ffc69ab, e1113eabea056260c65ddfa10e66e791f59a840b, e4382bba2f24d7c5d5ac971d81f687b12346ec35, c983b87c459711cd4b260f540e16316907d7dada, 35676104f56b7417b79bf42d719a18d947ac99ec, abc2edbf12f82d4a5feab45588a94f9ed2acd5fd, 133a0b4cc0aa3dba6bdca6e10153f40bce145002, 67bb241093ea2d10a257c97f898bab7464973ee8, e715c0f9457a921dce7a7fc99952e585fc0a295e, 6a9d8e5a7ec997d9561d150139807f2683c1c28e, 2c045428cd80d1b0dc20001de0ece48fef5b8066, 87905784670b871cefb639556ad3c230494b3426, 0439c07d87745586ece0593f3fce5ff08463e900, 1e745bd4dcc8bad4e4c3b67fcad4e31f793178e1, 4c11bdecc7505b9dc04115cd3ccd795f1ac7378f, 9d73ddc533fce498a5bef6d9ad3d745b8c055981, 0e1e50222da2f1b1e6f4394e797e8d4d868c70f6, 805f13c36eb6496ecd466fbcc3bfc97d320c8c75, c0d65ed56cdc4ad1700e990355931e076fb9e765, ab6860bc0a33b42608ccd978d487e3302fb20d09, 26a972ff54d05ccee60e0f632be6a0a3a87aed93, b8eecc0c232039f12362e7843334277890211549, bf427e4800b84ebff2536e1c13bc5d3a72b9cdef, fbe2947e3afce513e8b9c52cf0d7b432a78e48a1, f064a2224482f890f38ef1448ca5693d49892104, d30276b6dbb34a7a6a33f4e39bbd9b2a6bdee81b, 86030d041b203c0c42ef7edf07caefca4e75eace, 90c78d4c1f38eb5e620c14ca7bb8a7414a3def05, aed7f8fdddcd0a64cced957feb45cf6a49a97c4f, 052f38e5bc70375016b3112f743e6c7edae7c8ae, 939c996cebd8370aa8fd5771cb5d29e7cd47d6ca, 77b59442b7a00bcc96adbaac8252cc4cc986e321, be2db5e7a7f914a51fd41ef4c6133ab77454178f, 71bd3fd2952dca1502ff6adb847d309edb481006, f7bea4441cbf93c82a3bae94ef924a255092ffeb, e66a3f5d67e5f3de8d9b738841d4420e982668b0, 28fd863be83e1a6edbc452f05fcf80930568f19b, 74872ea8f6424e55c815af39b2c525814221d58e, 572089b4c38e6ff3d7d36afacc779b802554e905, 513ef9072167a0e197cf3330da4014f92126b3a9, c9a24692af5541cf8ae1ad67fdbc27694c7a5da7, 21eecdd2637b20bbf49587bc2abfa2fda752ce28, 40079f192af8597f776edbe45c0b6cdf7edb3a53, dfa106a62bc82668feabbb81adba123e662a0766, f62be3ab0a5a9858872f2012fc9c30cb2edb06c4, 77ca69c80a240be83a83c65e97bd8777f2e26246, 6253abc806ffcf528485b28addff478a0463c077, c1b31c0b896e23ce6182dd6b447e0553e0e08983, 0ca9f23a2f32a705bf85719e3df1add0a4f67d80, f73acc4bc7a5523e6aa979842cd52706a001eb49, b589282f4b5553b19d5be6c0dee788615b98264e)
• :white_check_mark: login: jstone-lucasfilm / name: Jonathan Stone (37f1ef563c67eda4b342fdb9684d3505dc32a5f7)

[jstone-lucasfilm]

@StefanHabel We'll be holding ASWF Dev Days 2024 on September 26th and 27th, so let us know if you might be interested in following up on this project then!

https://www.aswf.io/dev-days-2024/

[StefanHabel]

@StefanHabel We'll be holding ASWF Dev Days 2024 on September 26th and 27th, so let us know if you might be interested in following up on this project then!

https://www.aswf.io/dev-days-2024/

Absolutely, count me in!

Apologies for putting this on hold for so long.

Looking forward to it!