Draft : Data Library Template + Specification Generation tools#2451
Open
ld-kerley wants to merge 5 commits intoAcademySoftwareFoundation:mainfrom
Open
Draft : Data Library Template + Specification Generation tools#2451ld-kerley wants to merge 5 commits intoAcademySoftwareFoundation:mainfrom
ld-kerley wants to merge 5 commits intoAcademySoftwareFoundation:mainfrom
Conversation
ld-kerley
force-pushed
the
template/generate-spec-docs
branch
from
51fec25 to
5133fcf
Compare
This was referenced Sep 11, 2025
Allowing for significant reduction in the size of the source for the standard library Templates can be nested and replace multiple variables simultaneously Templates can be expanded and diff in cmake stage - allowing for easy validation of appropriate template expansion Leaves the libraries folder untouched for now, to facilitate easier hands on experimentation with the new grammar Also includes documentation building tools - which have been the proving ground for the new template grammar. Builds specification docs to a temporary folder (for now) from a new template location - again for easy validation that the expansion is correct. The documentation work was critical to ensuring this initial template system is fully featured enough to be useful, and uncovered a number of discrepancies with the human edited specification. This is one of the strong advantages of using a template expansion based system.
verified data library builds with zero diffs generated docs match everything discussed in AOUSD - modulo one out standing issue with colorcorrect node. includes fix for mistake when adding default to unifiednoise node
ld-kerley
force-pushed
the
template/generate-spec-docs
branch
from
367e160 to
f9e2c6e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This work is a continuation of the work in #2362. Please be sure to refer to the valuable discussion in that PR for more context around this work.
This PR contains three separate, but very interconnected pieces of work.
Both the template expansion tools and the specification build tools are still very much work-in-progress, and have not been cleaned up too much, in anticipation of possible updates to the new grammar.
The hope here is that we can merge this PR soon to allow people to iterate and experiment - as well as to avoid this working going stale and needing to be rebased (yet again). Everything in this PR should be disabled/optional and should not affect the existing functionality of the code, or understanding of the data library. The MaterialX data library contained in the "libraries" folder remains untouched by this PR.
Named Constants and Template Elements
The proposed formal specification for these elements is outlined in #2553.
Briefly the changes from the prior proposal are:
<constant>elements of their associated<typedef>.<template>elements can now be nested inside each other and evaluated from outer to inner scope. Examples of this are now in thestdlib_defs.mtlxin the templates directory.<template>elements can now substitute multiple name variables simultaneously.There is a build tool that will expand the templates.
Specification Build Tools
Building on top of the named constant and template work outlined above, we add tools to programmatically build the parameter tables for the new style MaterialX node specification (the designs for these tables has been contributed by the AoUSD).
These tools are important to include as part of this work, as they have been the proving ground, and have both extended the original proposed grammar and validated that both the system and the tools are functioning correctly.
The build tools are guarded behind the CMake argument
MATERIALX_BUILD_SPECIFICATION_DOCS, which is disabled by default. When enabled the markdown template files indocuments/SpecificationTemplateswill be expanded to adocuments/SpecificationBuildfolder along side - while this is still work-in-progress - ultimately we could build directly todocuments/Specification.Through the process of building this a number of inconsistencies were discovered, highlighting the benefits of generating the documents though an automatic system.
Additional attribute the documentation system uses during the build, but are stripped out while building the data library itself are:
spec_descto store the description fieldspec_acceptedvaluesto store the accepted values field