Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Plug-in arguments, visualise data #116
To facilitate configurable plug-ins in a manner similar to arguments provided to any function or class.
The idea is to let data in an instance influence a plug-in.
Instances may contain data that affect the operation of a plug-in, similar to how the arguments of a function or method affects it's operation.
The data is then accessible within the plug-in, like this:
class ExtractReview(Extractor): def process_instance(self, instance): assert instance.data('width') == 512
If we document these "arguments" utilising the same syntax used for documenting functions, methods and classes, we can make use of the automated documentation mechanisms of Sphinx along with providing uniform formatting and visualisation of plug-in arguments in our own GUIs.
Properly documented, users can know which attributes they can append to their instances in order to affects its output.
For example, this is how we influence the operation of a function.
>>> extract_review(width=500, height=256)
These arguments may be documented in the docstring of a plug-in, similar to regular classes.
def extract_review(width, height): """Extract a review Arguments: width (int): Width of output, in pixels height (int): Height of output, in pixels
This style of docstrings is called Google Napoleon and is supported by Sphinx, the documentation generator. Given this, Sphinx is able to generate nice-looking documentation and formatting.
Have a look here, click on "source" to see what it looks like originally.
Use in Plug-ins
A plug-in doesn't need an init, which is where arguments are normally specified when documented in the doc-string. But that doesn't stop us from documenting arguments provided by an instance.
class ExtractReview(Extractor): """Extract as image-sequence (png) Arguments: startFrame (float): Start frame of output endFrame (float): End frame of output width (int): Width of output in pixels
Sphinx will then pick this up and produce conveniently formatted documentation, our tools may then also use this information in the GUIs for users to know how to control their publishes.
If plug-ins are documented like this, we could provide helpful information to users in the GUI, so that they know which attributes they have access to, and what they do.
The data available within an instance can come from anywhere, such as directly from a Selector.
class MySelector(Selector): def process_context(self, context): inst = context.create_instance(name='MyInstance') inst.set_data('width', 500)
It can also come from any other source, like those available to host-specifics. E.g. Houdini may provide these options through a Digital Asset whereas After Effects may provide them as custom attributes on layers. Or, they can simply be hard-coded into the selector, where the selectors is picked upon start of a host. E.g. starting After Effects may include a particular set of selectors whereas Maya includes others.
This workflow is typically called wrappers or boot-strappers.