Plug in Documentation

Pyblish QML visualises documentation per-plugin, here are some best practices for writing it along with technical information about how the data is parsed before being displayed.

Behaviour

Documentation is taken from the __doc__ member of your plug-in class.

class MyValidator(...):
   """General description

   Longer description here.

As per PEP08, the first line of the above docstring is treated as a summary of the below description and used in the GUI right after drawing the name of the plug-in.

The longer portion is then shown when expanded.

If a line should be too long to display in the GUI, the end of it is elided.

Parsing

Before showing the docstring, it is parsed. Parsing is currently very straightforward and operates on two rules.

1. Remove all newlines
2. Keep paragraphs

This happens so as to ensure that the maximum amount of space is used in the GUI and to get rid of the leading tabs present in any docstring.

Which means that this...

class MyValidator(...):
   """General description

   Longer description
   here.

   """

translates into..

General description

Longer description here.

Caveats

As a side-effect of the above two rules, you cannot make lists or other entries that depend on newlines.