Developer Guide: Update Setup and Build MaterialX section

[MustafaJafar]

Change log Description

This PR adds a user-friendly developer guide providing examples and step by step guides for building MaterialX.

This PR was made at the Dev Days event on May 15, 2025. Thank you.

resolve #1483

[linux-foundation-easycla[bot]]

The committers listed above are authorized under a signed CLA.

• :white_check_mark: login: jstone-lucasfilm / name: Jonathan Stone (009279fca724bb487809e7a6d5bb21901808b956)

[ld-kerley]

Hi @MustafaJafar - thanks so much for this contribution - this looks like a good change to me. I know that @jstone-lucasfilm has been looking more closely at the developer documentation recently, so I'm going to request a review from him as well before we merge. He's on vacation this week, but may have some notes early next week.

[ashwinbhat]

Hi @MustafaJafar can you also add a comment on the issue so that we can assign it to you. Thanks again for all your help.

[MustafaJafar]

Tagging @jstone-lucasfilm for visibility. Please let me know if there are more comments to address. 😄

[MustafaJafar]

Tagging @jstone-lucasfilm for visibility. Please let me know if there are further comments. Many thank you.

[MustafaJafar]

Thanks for these updates, @MustafaJafar, and apologies for the delay in reviewing. Documentation is much more nuanced than code, and providing good review guidance requires a frame of mind more akin to a book editor than a software engineer, so it takes more thought and time. :)

No worries. I understand and to me, writing docs is like painting where we may need to take distance for some time.

Does that sound reasonable to you?

About the "Notes" and "Tips" sections: Personally, as a reader, I don't like hidden stuff. let's take the CONTRIBUTING.md page as example, it says clone the repo but it didn't mention that the repo has submodules although as I developer I can figure it out myself but who knows how long time it'll take me to figure it out.

This makes me think of the target audience, e.g. if this page for beginners, they'll mostly appreciate such hints.

About the new images: Other case with another audience is when an admin or an artist td who wants to get a build of materialx for example to try the materialx viewer or graph editor, they will mostly need additional guidance so that they know where to click the mouse button. that's why I tried being very explicit about the steps and show visuals.

Personally, I'll be more than happy to stick to the recommended doc style. Maybe I can give it a seconed thought to find a middle ground.

Please, let me know what do you think ^^.

[jstone-lucasfilm]

@MustafaJafar Good points, and for the detail about recursive cloning, I think my main recommendation would be to include this as an additional sentence at the end of the paragraph, without the use of the Note highlighting syntax. It's the use of the Note highlighting that breaks the flow of the existing documentation, at least to my eye.

Here's one proposal for this additional sentence, where I've restricted the recommendation to developers working on the command line, as developers using IDEs such as GitHub Desktop don't need to take any special steps to clone projects recursively:

The MaterialX project includes submodules, so developers cloning the project from the command line should include the --recurse-submodules flag in their command.

For the inclusion of images, I don't object to this idea in general, but I think we'll want to add images in a comprehensive way when we take this step, creating a consistent visual language for when images are included and when they are not. For now, I'd recommend keeping your proposal as simple as possible, and we can address the inclusion of images in a future update.

[MustafaJafar]

Hello @jstone-lucasfilm and @dbsmythe, In my last commit https://github.com/AcademySoftwareFoundation/MaterialX/pull/2388/commits/ec304f6d53ea6da657d1e5ef5be25328506cead9 , I've added CMake Generators section, added examples for linux and mac, tweaked some parts in docs to reflect that the provided examples are common combinations.