docs: data generators

[chrismclarke]

PR Checklist

• PR title descriptive (can be used in release notes)

Description

• Add documentation for data generators
• Include special use case for issue recently discovered

Review Notes

I haven't linked to example sheets as I couldn't remember if we have good examples of data generators or not

Author Notes

I don't think the example outlined has ever been coded into a debug/example template for the debug repo - might be useful to do so for easier reference

Dev Notes

The Special Case issue mentioned in the docs is particular to the case where the generator is used to create data_pipes, which in turn need to refer to @row variables. The @row is processed one level too soon (i.e. processed by the generator and not left for processing within the data_pipe).

I couldn't wrap my head around how best to go about making sure something like that doesn't happen in the code (felt like a lot of potential for knock-ons if too heavy-handed and hacky if writing single-level exceptions), so for now hopefully just having documented is sufficient (assume a pretty rare case)

Git Issues

Closes #

Screenshots/Videos

Rendered Doc

[esmeetewinkel]

Thanks for documenting this. I don't think I'd come across this case before, or if I did I didn't get to the bottom of it!