Update transformation_documentation_wrapper to use MRO

[sergisiso]

The main reason is all of the code is assume to rely on the presence of cls.apply when doing things such as inheriting the docstirng and generating the docstring for the validate function.

I'd also assumed it was needed for get_valid_options but I was smarter when coding that and it in fact uses the mro to find all of the apply methods in the hierarchy and skips over those that don't have one.

This is a flaw with the transformation_documentation_wrapper then - we could do better and only update apply if its on cls, and update validate according to the first apply method we find looping up the mro (similar to psyGen.py::2751-2754). I'm happy to fix this up soon if you'd like as I think it could be a relatively small task - if so can you open an issue and I'll also add a TODO to remove this apply method once that issue is resolved?

Originally posted by @LonelyCat124 in #3205 (comment)

[LonelyCat124]

So when looking at implementing #3330 I also came across another difficulty with the current implementation that would be better solved with MRO.

If you have a MetaTransformation with multiple inheritance, you can't use the same syntax for transformations as you would for normal Transformations, as the inherit=....option is not supported on the decorator. Instead, I have to specify:

# Multiple inheritance doesn't work with the decorator it seems.
transformation_documentation_wrapper(OpenMPCPURoutineTrans,
                                     inherit=[OMPLoopTrans,
                                              MaximalOMPParallelRegionTrans,
                                              OMPMinimiseSyncTrans])

to be called at the end of the file. Fundamentally, I think this is the same behaviour (or close enough) that I'm not too concerned yet, but it would be better if we could use MRO to handle multiple inheritance instead. I did check the .doc on the apply method and I get the inherited arguments, but I haven't checked the generated documentation yet.

The slight challenge is that the MRO is not "bottom to top" but just left to right and then goes up the entire ancestor stack of the first inherited class before the next, so we'd have to expand the entire MRO for all of the ancestor classes (which is fine, just overheads) to do so.

[LonelyCat124]

The main reason is all of the code is assume to rely on the presence of cls.apply when doing things such as inheriting the docstirng and generating the docstring for the validate function.

I'd also assumed it was needed for get_valid_options but I was smarter when coding that and it in fact uses the mro to find all of the apply methods in the hierarchy and skips over those that don't have one.

This is a flaw with the transformation_documentation_wrapper then - we could do better and only update apply if its on cls, and update validate according to the first apply method we find looping up the mro (similar to psyGen.py::2751-2754). I'm happy to fix this up soon if you'd like as I think it could be a relatively small task - if so can you open an issue and I'll also add a TODO to remove this apply method once that issue is resolved?

Originally posted by @LonelyCat124 in #3205 (comment)

@sergisiso I've been doing a bit more reading here and its not so straightforward. If the subclass doesn't have apply, then we can't make the generated docstring show the apply method on the class (as far as I can see from googling), so when you looked at the Transformations docstring you wouldn't see the apply method at all (so couldn't see the options without going to the superclass). Would you be ok with that? I kinda prefer each Transformations' sphinx page to show its apply and options.

[LonelyCat124]

The alternative is that the transformation docstring wrapper could add an apply method to the class that calls the superclasses apply, but that feels very hacky/potentially not safe