Plug in Documentation

Provide your users with thorough information of what to expect of a plug-in.

Introduction

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.

Purpose

The following are some guidelines to adhere to when writing documentation for your plug-in, but are in no way mandatory nor have any effect on the operation of Pyblish or Pyblish QML.

1. Provide a general understanding of what the plug-in is doing.
2. In case of a validator, propose general solutions and best-practices for how to avoid failing.
3. Do not provide specific solutions; save those for Exception Messages.

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.

Example