Document the preferences plugins system

src/calibre/customize/__init__.py

@@ -371,6 +371,13 @@ class InterfaceActionBase(Plugin): # {{{
 
 class PreferencesPlugin(Plugin): # {{{
 
+    '''
+    A plugin representing a widget displayed in the Preferences dialog.
+
+    This plugin has only one important method :meth:`create_widget`. The
+    various fields of the plugin control how it is categorized in the UI.
+    '''
+
     supported_platforms = ['windows', 'osx', 'linux']
     author         = 'Kovid Goyal'
     type = _('Preferences')
@@ -406,7 +413,8 @@ class PreferencesPlugin(Plugin): # {{{
     def create_widget(self, parent=None):
         '''
         Create and return the actual Qt widget used for setting this group of
-        preferences. The widget must implement the ConfigWidgetInterface.
+        preferences. The widget must implement the
+        :class:`calibre.gui2.preferences.ConfigWidgetInterface`.
 
         The default implementation uses :attr:`config_widget` to instantiate
         the widget.

src/calibre/gui2/preferences/__init__.py

@@ -20,21 +20,42 @@ class ConfigWidgetInterface(object):
 
     '''
     This class defines the interface that all widgets displayed in the
-    Preferences dialog must implement. To create a plugin for a new
+    Preferences dialog must implement. See :class:`ConfigWidgetBase` for
+    a base class that implements this interface and defines various conveninece
+    methods as well.
     '''
 
+    #: This signal must be emitted whenever the user changes a value in this
+    #: widget
     changed_signal = None
+
+    #: Set to True iff the :meth:`restore_to_defaults` method is implemented.
     supports_restoring_to_defaults = True
+
+    #: The tooltip for the Restore to defaults button
     restore_defaults_desc = _('Restore settings to default values. '
             'You have to click Apply to actually save the default settings.')
 
     def genesis(self, gui):
+        '''
+        Called once before the widget is displayed, should perform any
+        necessary setup.
+
+        :param gui: The main calibre graphical user interface
+        '''
         raise NotImplementedError()
 
     def initialize(self):
+        '''
+        Should set all config values to their initial values (the values
+        stored in the config files).
+        '''
         raise NotImplementedError()
 
     def restore_defaults(self):
+        '''
+        Should set all config values to their defaults.
+        '''
         pass
 
     def commit(self):
@@ -47,6 +68,12 @@ class ConfigWidgetInterface(object):
         return False
 
     def refresh_gui(self, gui):
+        '''
+        Called once after this widget is committed. Responsible for causing the
+        gui to reread any changed settings. Note that by default the GUI
+        re-initializes various elements anyway, so most widgets won't need to
+        use this method.
+        '''
         pass
 
 class Setting(object):
@@ -175,6 +202,20 @@ class CommaSeparatedList(Setting):
 
 class ConfigWidgetBase(QWidget, ConfigWidgetInterface):
 
+    '''
+    Base class that contains code to easily add standard config widgets like
+    checkboxes, combo boxes, text fields and so on. See the :meth:`register`
+    method.
+
+    This class automatically handles change notification, resetting to default,
+    translation between gui objects and config objects, etc. for registered
+    settings.
+
+    If your config widget inherits from this class but includes setting that
+    are not registered, you should override the :class:`ConfigWidgetInterface` methods
+    and call the base class methods inside the overrides.
+    '''
+
     changed_signal = pyqtSignal()
     supports_restoring_to_defaults = True
 
@@ -186,6 +227,21 @@ class ConfigWidgetBase(QWidget, ConfigWidgetInterface):
 
     def register(self, name, config_obj, gui_name=None, choices=None,
             restart_required=False, empty_string_is_None=True, setting=Setting):
+        '''
+        Register a setting.
+
+        :param name: The setting name
+        :param config: The config object that reads/writes the setting
+        :param gui_name: The name of the GUI object that presents an interface
+                         to change the setting. By default it is assumed to be
+                         ``'opt_' + name``.
+        :param choices: If this setting is a multiple choice (combobox) based
+                        setting, the list of choices. The list is a list of two
+                        element tuples of the form: ``[(gui name, value), ...]``
+        :param setting: The class responsible for managing this setting. The
+                        default class handles almost all cases, so this param
+                        is rarely used.
+        '''
         setting = setting(name, config_obj, self, gui_name=gui_name,
                 choices=choices, restart_required=restart_required,
                 empty_string_is_None=empty_string_is_None)

src/calibre/manual/plugins.rst

@@ -173,3 +173,11 @@ Preferences Plugins
    :members:
    :member-order: bysource
 
+.. autoclass:: calibre.gui2.preferences.ConfigWidgetInterface
+   :members:
+   :member-order: bysource
+
+.. autoclass:: calibre.gui2.preferences.ConfigWidgetBase
+   :members:
+   :member-order: bysource
+