Documentation : Add Example files to Gaffer distribution and expose in the UI

[themissingcow]

Gaffer examples can now be registered with Gaffer at startup using the GafferUI.Examples.registerExample function. Registered Examples
are available in the Help menu.

Examples can optionally be associated with certain node types. The Cog
menu in the Node Editor will then list any applicable Examples for the Node
type being edited.

The examples themselves are work-in-progress. This initial PR contains two
Arnold examples for review.

User Changes:

• Help > Examples will now list any registered Examples
• Node Editor -> <cog> -> Examples

API Additions:

• GafferUI.Examples
• GafferUITest.TestCase.assertExampleFilesExist

[themissingcow]

I have some plans to improve the documentation within the Backdrops in the examples, but in the mean time, please C+C on wording/etc..

[themissingcow]

After discussion today, will move the Gaffer files from doc/examples to resources/examples.

[medubelko]

One nitpick: let's name the directory resources/demos to be consistent with the existing docs.

[johnhaddon]

One nitpick: let's name the directory resources/demos to be consistent with the existing docs.

We've called the API registerExample(), and the menu is called "/Help/Examples", so for consistency I'd prefer resources/examples. To me "Example" comes across better than the informal/abbreviated "Demo".

[medubelko]

I think "Demo" makes more sense in the context of the articles, so maybe they'll just have to be inconsistent?

[johnhaddon]

The articles will refer to the menu item though won't they? Isn't a demonstration something performed by somebody, while an example is something sitting there to be looked at?

[themissingcow]

I've added in the files for the Spherical/Anamorphic Camera setups from the Documentation. For now, they're in with the rest of them. Be good to work out if this is the right place, and how to then best link them from the docs, etc... I had to add them in somewhere so they'd be available in the distribution so they could be immediately opened in Gaffer from the menu. I couldn't find them anywhere in the current release.

Feel free to suggest any renaming of menu items/etc... or copy changes in the Backdrop nodes. Would appreciate a proof-read if anyone has any time :)

[andrewkaufman]

Just FYI, I merged #2943 which adds some more demo/example files. I presume you'll want an update here to account for those as well.

[medubelko]

Isn't a demonstration something performed by somebody, while an example is something sitting there to be looked at?

Perhaps it's video game argot peeking through, but I associate a "demo" that lacks an active teacher with something like "a contrived derivative of a product, output, process, or idea, meant for illustration or practical explanation."

From what we have already, an "example" can range between a nugget of an idea and a full implementation, and the word comes out too readily in sentences ("for example, let's look at", "take, for example", "keeping in mind the above examples"), so I don't think its meaning will be precise enough in the docs themselves.

Anyway, I don't want to stall this. Like I said, feel free to use "example" in the API. We don't have to match perfectly: the docs lack the extra context that the application provides, and I already use over-specific or redundant phrases ("the StandardAttributes node", "the File Name plug", "the aperture parameter") to guarantee clarity. In the API and the menu, I can't think of any conflicting or generic meaning of "example".

[medubelko]

I've added in the files for the Spherical/Anamorphic Camera setups... I couldn't find them anywhere in the current release.

That's my fault, due to them being omitted from the most recent release. There's no issue in duplicating them, since when we move them to the Resources project they'll need to be duplicated anyway.

[medubelko]

Feel free to suggest any renaming of menu items/etc... or copy changes in the Backdrop nodes. Would appreciate a proof-read if anyone has any time :)

For visibility: I've migrated the backdrop text to Google Drive, where it'll be easier for Tom and I to collaborate on changes.

[johnhaddon]

There's no issue in duplicating them, since when we move them to the Resources project they'll need to be duplicated anyway.

We don't need to move them to the resources project - that's for big binary blobs that we don't want in the main repo, and don't really need to be versioned in the same way. These are nice little lumps of text that we might want to update/version alongside the docs, so they're best kept in the main repo. The issue in duplicating them is that we won't know which one to edit and they'll get out of sync, so we should just have the one version. It doesn't matter that they weren't released in 0.53 - they're in master where this PR branches from, and Tom has found them now.

Perhaps it's video game argot peeking through

I think the association with video games is one of the things that makes it sound a bit odd to me.

From what we have already, an "example" can range between a nugget of an idea and a full implementation, and the word comes out too readily in sentences ("for example, let's look at", "take, for example", "keeping in mind the above examples"), so I don't think its meaning will be precise enough in the docs themselves.

I don't really buy it. To be clear, all I'm suggesting is that we rename the "Demos" heading to "Examples", and then replace the download links that are a pain to use with pointers to the "/Help/Examples/TheExample" menu items.

We are rather quibbling over esoterica here, but I want to repeat a point I've made before. Our users cover a broad spectrum of technical ability/interest, but they're not static on that spectrum. Artists pick up a bit of scripting here and there and one day end up writing C++, and coders have even been known to make the odd picture here and there. Keeping consistent terminology through the API and documentation facilitates those transitions...

[medubelko]

We don't need to move them to the resources project - that's for big binary blobs that we don't want in the main repo

Ah, that's good. I wasn't sure of the criterion. This frees me up to put sample reference files in the main repo.

"Demos" heading to "Examples"

I concede, but can the heading be "Example Graphs"? I admit that such specificity is just as applicable to the existing "Demos" headings.

replace the download links that are a pain to use

Agreed.

[johnhaddon]

I concede, but can the heading be "Example Graphs"?

It's a deal!

[medubelko]

Tom, I've provided a more complete edit of the remaining examples on Drive. I think it's best if I let you review the suggestions I've made, and then we can reconvene for a second round of edits and cleanup.

[themissingcow]

@medubelko Thanks for the most excellent feedback on the copy in the examples. I've updated all the examples to reflect the comments in the Drive doc. I've also remove the Light Linking example as yours is much better!
I made a start updating the docs to point to the menu items, be great to get your feedback on the right way/place to insert the menu reference. I wasn't able to build the docs to check due to the Macbeth issue.

[medubelko]

the right way/place to insert the menu reference

I haven't built this branch yet to see it in full context, but it should be similar to how I've pointed to menu entries before:

On the menu bar, go to _Help_ > _Examples_ > _Compositing_ > _Contact sheet_

On the menu bar, go to Help > Examples > Compositing > Contact sheet

You won't need to include "on the menu bar" each time, but I wanted to provide it in use in a sentence.

[themissingcow]

@medubelko Thanks for the out-of-band feedback, I've integrated all those changes, and menu items are referenced as per your prior art.

I tried to build the Docs, but on OSX it seemed to look a little off (a lot of the screenshots aren't marked up in the right places, and the page formatting is a little off). I wondered if it was a Sphinx version issue or similar. Are you able to build this PR to checks working as expected still? I should have access to a Linux machine in the coming weeks so can hopefully resolve this then.

[johnhaddon]

Hey Tom,
Just made a couple of last minute comments. Could you take care of those at the same time as rebasing on the latest master (the rebase should fix the build errors on Travis).
Cheers...
John

[johnhaddon]

This will break for any non-arnold-supporting builds. See other startup files for the except ImportError approach we take to that.

[themissingcow]

So does GafferArnoldUI always load even if Arnold isn't supported in the build? Wondered if

gaffer/startup/gui/menus.py

Line 101 in 80d6eea

if moduleSearchPath.find( "arnold" ) :

would stop it loading the module.

[johnhaddon]

If Arnold isn't supported in the build, then GafferArnoldUI won't exist. The approach we take is this :

• Everywhere except startup/gui/menus.py, we catch ImportError and silently fail.
• In startup/gui/menus.py we report errors rather than suppress them, so we only report the error in one place. We assume that if the user has gone to the trouble of putting arnold on PYTHONPATH, then they are expected to be able to use it, and any problem in loading GafferArnold should be reported.

This is slightly academic perhaps, because all public builds ship with Arnold support. But I want to maintain the possibility for a studio to maintain an internal build without Arnold support, instead using some other renderer.

[themissingcow]

Sure thing, will add in, thanks - just thought that the GafferArnoldUI startup directory wouldn't be loaded unless GafferArnoldUI was initialising...

[themissingcow]

Updated and pushed

[johnhaddon]

Sorry, wait, I'm talking nonsense again. You are right, GafferArnoldUI won't even exist in this case. I only recently fixed that, which I think is why I was getting confused.

[themissingcow]

Un-updated and pushed :)

[medubelko]

@themissingcow I did a pseudo-code review.

Big picture thing to think about: I built and tested the branch, and one thing jumped out at me – the examples are not read-only by default. In local Gaffer installs, where a user has not necessarily made the files read-only, they might play around with the example and accidentally save. Further, just clicking around the graph can cause backups to generate, leading to the "Load backup?" dialog on subsequent load, which seems inappropriate. In retrospect, this is an issue with all of the files in /resources and /doc, but we don't (to my knowledge) encourage users to put themselves in circumstances where they could write to them. It seems quite likely to me that they might accidentally overwrite an example.

[medubelko]

'Example: Box node basics'

[medubelko]

Actually, it looks like this one snuck back in.

[medubelko]

I tried to build the Docs, but on OSX it seemed to look a little off (a lot of the screenshots aren't marked up in the right places, and the page formatting is a little off). I wondered if it was a Sphinx version issue or similar.

I suspect this has to do with font sizing. Can you create an issue and upload sample images of where it looks wrong?

Are you able to build this PR to checks working as expected still?

Everything seemed to work fine on my end.

[themissingcow]

Big picture thing to think about: I built and tested the branch, and one thing jumped out at me – the examples are not read-only by default. In local Gaffer installs, where a user has not necessarily made the files read-only, they might play around with the example and accidentally save. Further, just clicking around the graph can cause backups to generate, leading to the "Load backup?" dialog on subsequent load, which seems inappropriate. In retrospect, this is an issue with all of the files in /resources and /doc, but we don't (to my knowledge) encourage users to put themselves in circumstances where they could write to them. It seems quite likely to me that they might accidentally overwrite an example.

Yeah, its a really good point - John and I were discussing this. I think we meant to work out a good place to do the 'read-only' thing and then, erm, didn't :). Let us have a think and try and work out something that makes sense. Good point re: the backups too.

[themissingcow]

I suspect this has to do with font sizing. Can you create an issue and upload sample images of where it looks wrong?

Sure thing, I'll take this out-of-band and we can always make a new issue if its a general OSX thing. It might be as I have 1 retina screen and one not. I think it might affect the resolution of screengrabs even on the non-retina screen.

Everything seemed to work fine on my end.

👍 great, appreciate you checking.

[themissingcow]

Yeah, its a really good point - John and I were discussing this. I think we meant to work out a good place to do the 'read-only' thing and then, erm, didn't :). Let us have a think and try and work out something that makes sense. Good point re: the backups too.

@medubelko We believe we have addressed this in 9618c38, we now open any examples from the Help menu as an 'untitled copy'. As such, there won't be any .gafferBackups under $GAFFER_ROOT and the user would need to specify a path in order to save. We did this instead of marking them read-only as the Gaffer UI prevents you from editing Nodes in read-only files - which seemed unhelpful for an example... What do you think?

@johnhaddon Please may you sanity-check the implementation?

[johnhaddon]

@johnhaddon Please may you sanity-check the implementation?

LGTM. Looks like we have a build error on Travis though :

NameError: name 'docEnv' is not defined:
  File "/home/travis/build/GafferHQ/gaffer/SConstruct", line 1317:
    fileInstall = docEnv.Command( f.replace( "doc/", "$BUILD_DIR/resources/", 1 ), f, Copy( "$TARGET", "$SOURCE" ) )

I think this might be because we don't (yet) build the docs on Travis, so Sphinx doesn't exist. I don't think we need to use docEnv to do the examples install though do we, we could just use env?

[themissingcow]

I think this might be because we don't (yet) build the docs on Travis, so Sphinx doesn't exist. I don't think we need to use docEnv to do the examples install though do we, we could just use env?

Oh rubbish, sorry. Sorted.

[medubelko]

LGTM. Thanks Tom.

[medubelko]

Actually, it looks like this one snuck back in.

[themissingcow]

@medubelko Sorry - thought I had them all. Should be good now! Thanks.