New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Plug-in arguments, visualise data #116

Open
mottosso opened this Issue Oct 8, 2014 · 0 comments

Comments

Projects
None yet
1 participant
@mottosso
Copy link
Member

mottosso commented Oct 8, 2014

Goal

To facilitate configurable plug-ins in a manner similar to arguments provided to any function or class.

Architecture

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.

image

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.

Pure-function example

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.

GUI Example

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.

image

Non-Maya instances

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.

@mottosso mottosso added the feature label Oct 8, 2014

@mottosso mottosso changed the title Plug-in arguments Plug-in arguments, visualise data Aug 17, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment