Commits

Aleš Erjavec committed c2d2400

Fixes for Widgets Development documentation.

Comments (0)

Files changed (10)

docs/extend-widgets/rst/basics.rst

 one, that will receive a data set on the input and will output a data
 set with 10% of the data instances. Not to mess with other widgets, we
 will create a Test directory within OrangeWidgets directory, and write
-the widget in a file called `OWDataSamplerA <OWDataSamplerA.py>`: OW for Orange Widget,
+the widget in a file called `OWDataSamplerA.py`: OW for Orange Widget,
 DataSampler since this is what widget will be doing, and A since we
 prototype a number of this widgets in our tutorial.
 
 setting the GUI of a widget and sending an empty token to the
 output channel.
 
-Although our widget is now ready to test, for a final touch, let's
-design an icon for our widget. As specified in the widget header, we
-will call it `DataSamplerA.png <DataSamplerA.png>`_ and will
-put it in icons subdirectory of OrangeWidgets directory (together with
-all other icons of other widgets).
+..
+   Although our widget is now ready to test, for a final touch, let's
+   design an icon for our widget. As specified in the widget header, we
+   will call it :download:`DataSamplerA.png <DataSamplerA.png>` and will
+   put it in icons subdirectory of OrangeWidgets directory (together with
+   all other icons of other widgets).
 
 For a test, we now open Orange Canvas. There should be a new pane in a
 widget toolbox called Test (this is the name of the directory we have

docs/extend-widgets/rst/channels.rst

 widget are defined by::
 
     self.inputs = [("Data", ExampleTable, self.dataset),
-               ("Learner", orange.Learner, self.learner, Multiple)]
+                   ("Learner", orange.Learner, self.learner, Multiple + Default)]
 
 Notice that everything is pretty much the same as it was with
 widgets from previous lessons, the only difference being
 widget can receive the input only from one widget and is not the default input
 channel for its type (more on default channels later).
 
+.. note:: :obj:`Default` flag here is used for illustration. Since *Learner*
+          channel is the only channel for a :class:`orange.Learner` type
+          it is also the default.
+
 How does the widget know from which widget did the token come from?
 In Orange, tokens are sent around with an id of a widget that is
-sending the token (essentially, with a pointer to the corresponding
-widget object), and having a multi-input channel only tells Orange to
+sending the token, and having a multi-input channel only tells Orange to
 send a token together with sending widget id, the two arguments with
 which the receiving function is called. For our :obj:`Learner`
 channel the receiving function is :obj:`learner`, and this looks
 the easy by which new scoring functions are added to the widget, since
 all that is needed is the augmenting the list ::
 
-    self.scoring = [("Classification Accuracy", orngStat.CA),\
-                ("AUC", orngStat.AUC), \
-                ("BrierScore", orngStat.BrierScore),\
-                ("Information Score", orngStat.IS),\
-                ("Sensitivity", orngStat.sens), \
-                ("Specificity", orngStat.spec)]
+    self.scoring = [("Classification Accuracy", orngStat.CA),
+                    ("AUC", orngStat.AUC),
+                    ("BrierScore", orngStat.BrierScore),
+                    ("Information Score", orngStat.IS),
+                    ("Sensitivity", orngStat.sens),
+                    ("Specificity", orngStat.spec)]
 
 which is defined in the initialization part of the widget. The
 other useful trick in this widget is that evaluation (k-fold cross
 probability estimates as obtained from the evaluation procedure. Which
 essentially means that switching from one to another scoring function
 (and displaying the result in the table) takes only a split of a
-second. To see the rest of the widget, check out `its code <OWLearningCurveA.py>`_.
+second. To see the rest of the widget, check out
+:download:`its code <OWLearningCurveA.py>`.
 
 *****************************
 Using Several Output Channels
 
     self.outputs = [("Sampled Data", ExampleTable), ("Other Data", ExampleTable)]
 
-We used this in the third incarnation of `data sampler widget <OWDataSamplerC.py>`_,
+We used this in the third incarnation of :download:`data sampler widget <OWDataSamplerC.py>`,
 with essentially the only other change in the code in the :obj:`selection` and
 :obj:`commit` functions::
 
 
 When enlisting the input channel of the same type, the non-default
 channels have a special flag in the channel specification list. So for
-our new `learning curve <OWLearningCurveB.py>`_ widget, the
+our new :download:`learning curve <OWLearningCurveB.py>` widget, the
 channel specification is::
 
     self.inputs = [("Train Data", ExampleTable, self.trainset, Default),
-               ("Test Data", ExampleTable, self.testset),
-               ("Learner", orange.Learner, self.learner, Multiple)]
+                   ("Test Data", ExampleTable, self.testset),
+                   ("Learner", orange.Learner, self.learner, Multiple)]
 
 That is, the :obj:`Train Data` channel is a single-token
 channel which is a default one (third parameter). Note that the flags can
-be added (or OR-d) together so :obj:`Default + Multi` is a valid flag.
+be added (or OR-d) together so :obj:`Default + Multiple` is a valid flag.
 To test how this works, connect a file widget to a learning curve widget and
 - nothing will really happen:
 

docs/extend-widgets/rst/contextsettings.rst

 Context-Dependent Settings
 ##########################
 
-You have already learned about :obj:`storing widget settings <settings>`.
+You have already learned about :doc:`storing widget settings <settings>`.
 But there's more: some settings are context
 dependent. Open Orange Canvas and observe the scatter plot - feed it
 some data, select two attributes for x- and y-axis, select some
 
 Here's the widget's :obj:`__init__` function.
 
-Part of `OWAttributeSampler.py <OWAttributeSampler.py>`_::
+Part of :download:`OWAttributeSampler.py <OWAttributeSampler.py>`::
 
     def __init__(self, parent=None, signalManager=None):
         OWWidget.__init__(self, parent, signalManager, 'AttributeSampler')
 When the widget gets the data, a function :obj:`dataset` is
 called.
 
-Part of `OWAttributeSampler.py <OWAttributeSampler.py>`_::
+Part of :download:`OWAttributeSampler.py`::
 
     def dataset(self, data):
         self.classAttrCombo.clear()
             ContextField("attributeList", DomainContextHandler.SelectedRequiredList,
                          selected="selectedAttributes")])}
 
-(More about these shortcuts in the `technical information about settings <settings-technical.htm>`).
-
 Why the dictionary and the empty string as the key? A widget can
 have multiple contexts, depending, usually, on multiple input
 signals. These contexts can be named, but the default name is empty
 changing functions yourself. Here's what you have to do with the
 function :obj:`dataset`
 
-Part of `OWAttributeSampler.py <OWAttributeSampler.py>`::
+Part of :download:`OWAttributeSampler.py`::
 
     def dataset(self, data):
         self.closeContext()
 When writing such callback functions make sure that the data you
 store is picklable and short enough, so you won't blow up the .ini
 files that store these settings.
-
-For more information about context handling, see the `technical information about
-settings <settings-technical.htm>`_.

docs/extend-widgets/rst/graphing.rst

 instances of one class should be plotted in scatter plot and parallel
 axis plot using the same color. Developers are thus advised to use
 :obj:`ColorPaletteHSV`, which is provided as a method within
-:obj:`OWWidget` class. :obj:`ColorPaletteHSV` takes an
+:mod:`OWWidget` module. :obj:`ColorPaletteHSV` takes an
 integer as an attribute, and returns a list of corresponding number of
 colors. In our learning curve widget, we use it within a function that
 sets the list box with learners::
 defined in the initialization of the widget using::
 
     self.cbox = OWGUI.widgetBox(self.controlArea, "Learners")
-    self.llb = OWGUI.listBox(self.cbox, self, "selectedLearners", selectionMode=QListWidget.MultiSelection, callback=self.learnerSelectionChanged)
+    self.llb = OWGUI.listBox(self.cbox, self, "selectedLearners",
+                             selectionMode=QListWidget.MultiSelection,
+                             callback=self.learnerSelectionChanged)
 
     self.llb.setMinimumHeight(50)
     self.blockSelectionChanges = 0
 graph (the user just selected a learner)::
 
     def learnerSelectionChanged(self):
-        if self.blockSelectionChanges: return
+        if self.blockSelectionChanges:
+            return
         for (i,lt) in enumerate(self.learners):
             l = lt[1]
             if l.isSelected != (i in self.selectedLearners):
                 self.graph.replot()
             l.isSelected = i in self.selectedLearners
 
-The complete code of this widget is available `here <OWLearningCurveC.py>`_. 
+The complete code of this widget is available :download:`here <OWLearningCurveC.py>`. 
 This is almost like a typical
 widget that is include in a standard Orange distribution, with a
 typical size just under 300 lines. Just some final cosmetics is needed

docs/extend-widgets/rst/index.rst

    plots
    contextsettings
 
-`Code and icons <code.zip>`_ from the tutorial. To learn where to put Python
-files and icons, read :doc:`Getting Started <basics>`.
-
 
 *********
 Reference

docs/extend-widgets/rst/owgui.rst

 line of code can construct a check box, line edit or a combo, make it being
 synchronized with a Python object's attribute (which, by the way, gets
 automatically saved and retrieved when the widgets is closed and reopened),
-attaches a callback function to the control, make it disable or enable other controls...
+attaches a callback function to the control, make it disable or enable other
+controls...
 
 *****************
 Common Attributes
 controls will only list their specific arguments, while the arguments which are
 presented here will only be described in cases where they have a different meaning.
 
-widget (required)
-Widget on which control will be drawn - can be widget's :obj:`controlArea` or another box.
+`widget` (required)
+   Widget on which control will be drawn - can be widget's :obj:`controlArea`
+   or another box.
 
-master (required)
-Object which includes an attribute that are used to store control's
-state, most often the object which called the function that
-initialized the control.
+`master` (required)
+   Object which includes an attribute that are used to store control's
+   state, most often the object which called the function that
+   initialized the control.
 
-value (required)
-String with the name of the master's attribute that synchronizes with the
-state of the control (and vice-versa - when this attribute is changed, the control changes as well). This attribute should usually be also included the master's :obj:`settingsList`, so that it is automatically saved and retrieved.
+`value` (required)
+   String with the name of the master's attribute that synchronizes with the
+   state of the control (and vice-versa - when this attribute is changed, the control changes as well). This attribute should usually be also included the master's :obj:`settingsList`, so that it is automatically saved and retrieved.
 
-box (default: None)
-Indicates if there should be a box that is drawn around the control. If :obj:`box` is :obj:`None`, no box is drawn; if it is a string, it is also used as box's name. If :obj:`box` is any other true value (such as :obj:`True` :), an unlabeled box is drawn.
+`box` (default: None)
+   Indicates if there should be a box that is drawn around the control. If `box` is ``None``, no box is drawn; if it is a string, it is also used as box's name. If `box` is any other true value (such as ``True`` :), an unlabeled box is drawn.
 
-callback (default: None)
-A function to be called when the state of the control is changed. Can include a single function, or a list of functions that will be called in the order provided. If callback function changes the value of the controlled attribute (the one given as the :obj:`value` argument described above) it may trigger a cycle; a simple trick to avoid this is shown in the description of <a href="#listBox">listBox function</a>.
+`callback` (default: None)
+   A function to be called when the state of the control is changed. Can
+   include a single function, or a list of functions that will be called in
+   the order provided. If callback function changes the value of the controlled
+   attribute (the one given as the `value` argument described above) it may
+   trigger a cycle
 
-tooltip (default: None)
-A string that is displayed in a tooltip that appears when mouse is over the control.
+   ..
+      ; a simple trick to avoid this is shown in the description
+      of :func:`listBox` function.
 
-label (default: None)
-A string that is displayed as control's label.
+`tooltip` (default: None)
+   A string that is displayed in a tooltip that appears when mouse is over the control.
 
-labelWidth (default: None)
-Sets the label's width. This is useful for aligning the controls.
+`label` (default: None)
+   A string that is displayed as control's label.
 
-orientation (default: "vertical")
-When label is used, determines the relative placement of the label and the control. Label can be above the control, "vertical", or in the same line with control, "horizontal". Instead of "vertical" and "horizontal" you can also use :obj:`True` and :obj:`False` or 1 and 0, respectively. (Remember this as "vertical" being the usual order of controls in the widgets, so vertical is "true".)
+`labelWidth` (default: None)
+   Sets the label's width. This is useful for aligning the controls.
 
-disabled (default: False)
-Tells whether the control be disabled upon the initialization.
+`orientation` (default: "vertical")
+   When label is used, determines the relative placement of the label and the control. Label can be above the control, "vertical", or in the same line with control, "horizontal". Instead of "vertical" and "horizontal" you can also use ``True`` and ``False`` or 1 and 0, respectively. (Remember this as "vertical" being the usual order of controls in the widgets, so vertical is "true".)
 
-addSpace (default: False)
-If true, a space of 8 pixels is added after the widget by calling :obj:`OWGUI.separator`. :obj:`addSpace` can also be an integer specifying the height of the added space.
+`disabled` (default: False)
+   Tells whether the control be disabled upon the initialization.
+
+`addSpace` (default: False)
+   If true, a space of 8 pixels is added after the widget by calling :func:`separator`. `addSpace` can also be an integer specifying the height of the added space.
 
 
 ********
 Check box, a wrapper around QCheckBox, adding a label, box, tooltip, callback
 and synchronization with the designated widget's attribute.
 
-checkBox(widget, master, value, label[, box, tooltip, callback, disabled, labelWidth, disables])
+.. function:: checkBox(widget, master, value, label[, box, tooltip, callback, disabled, labelWidth, disables])
 
-disables (default: [])
-If the check box needs to disable some other controls they can be given in list  :obj:`disables`, e.g. :obj:`disables=[someOtherCheckBox, someLineEdit]`. If the other control should be disabled when the checkbox is checked, do it like this: :obj:`disables=[someOtherCheckBox, (-1, someLineEdit)]` - now :obj:`someOtherCheckBox` will be enabled when this check box is checked, while :obj:`someLineEdit` will be enabled when the check box is unchecked.
+   `disables` (default: [])
+      If the check box needs to disable some other controls they can be given in list  `disables`, e.g. ``disables=[someOtherCheckBox, someLineEdit]``. If the other control should be disabled when the checkbox is checked, do it like this: ``disables=[someOtherCheckBox, (-1, someLineEdit)]`` - now `someOtherCheckBox` will be enabled when this check box is checked, while `someLineEdit` will be enabled when the check box is unchecked.
 
-labelWidth (default: None)
-:obj:`labelWidth` can be used to align this widget with others.
+   `labelWidth` (default: None)
+      `labelWidth` can be used to align this widget with others.
 
 
 Line Edit
 
 Edit box, a wrapper around QLineEdit.
 
-lineEdit(widget, master, value[, label, labelWidth, orientation, box, tooltip, callback, valueType, validator, controlWidth])
+.. function:: lineEdit(widget, master, value[, label, labelWidth, orientation, box, tooltip, callback, valueType, validator, controlWidth])
 
+   `valueType` (default: str)
+      A type into which the value is cast.
 
-valueType (default: str)
-A type into which the value is cast.
-
-validator (default: None)
-A standard Qt validator that can be associated with the control.
+   `validator` (default: None)
+      A standard Qt validator that can be associated with the control.
 
 
 Button
 A wrapper around QPushButton, just to be able to define a button
 and its callback in a single line.
 
-button(widget, master, label[, callback, disabled, tooltip])
+.. function:: button(widget, master, label[, callback, disabled, tooltip])
 
 
 Radio Buttons
 *************
 
-OWGUI can create an individual radio button or a box of radio buttons or an individual radio button.
+OWGUI can create an individual radio button or a box of radio buttons or an
+individual radio button.
 
 An individual radio button is created by :obj:`radioButton`.
 
-radioButton(widget, master, value, label[, box, tooltip, callback, addSpace])
+.. function:: radioButton(widget, master, value, label[, box, tooltip, callback, addSpace])
 
-The function provides the usual capabilities of OWGUI controls. It is though 
-your responsibility to put it in something like a :obj:`QVButtonGroup`.
+   The function provides the usual capabilities of OWGUI controls. It is though 
+   your responsibility to put it in something like a :obj:`QVButtonGroup`.
 
 A box of radio buttons is created by function :obj:`radioButtonsInBox`.
 
+.. function:: radioButtonsInBox(widget, master, value, btnLabels[, box, tooltips, callback)
 
-radioButtonsInBox(widget, master, value, btnLabels[, box, tooltips, callback)
+   `value` (required)
+      Synchronized with the index of the selected radio button.
 
-value (required)
-Synchronized with the index of the selected radio button.
+   `btnLabels` (required)
+      A list with labels for radio buttons. Labels can be strings or pixmaps.
 
-btnLabels (required)
-A list with labels for radio buttons. Labels can be strings or pixmaps.
-
-tooltips (default: None)
-A list of tooltips, one for each button.
+   `tooltips` (default: None)
+      A list of tooltips, one for each button.
 
 
 Combo Box
 
 A wrapper around QComboBox.
 
-comboBox(widget, master, value[, box, label, labelWidth, orientation, items, tooltip, callback, sendSelectedValue, valueType, control2attributeDict, emptyString])
+.. function:: comboBox(widget, master, value[, box, label, labelWidth, orientation, items, tooltip, callback, sendSelectedValue, valueType, control2attributeDict, emptyString])
 
-<dl class="attributes">
-items (default: [])
-A list of combo box's items. Unlike most OWGUI, :obj:`items` have one Orange-specific quirk: its element can be either a string, in which case it is used as a label, or a tuple, where the first element is a label name and the last is the attribute type which is used to create an icon. Most attribute lists in Orange Widgets are constructed this way.
+   `items` (default: [])
+      A list of combo box's items. Unlike most OWGUI, `items` have one Orange-specific quirk: its element can be either a string, in which case it is used as a label, or a tuple, where the first element is a label name and the last is the attribute type which is used to create an icon. Most attribute lists in Orange Widgets are constructed this way.
 
-sendSelectedValue (default: 0)
-If false, attribute :obj:`value` will be assigned the index of the selected item. Otherwise, it is assigned the currently selected item's label.
+   `sendSelectedValue` (default: 0)
+      If false, attribute `value` will be assigned the index of the selected item. Otherwise, it is assigned the currently selected item's label.
 
-control2attributeDict (default: {})
-A dictionary for translating the item's label into :obj:`value`. It is used only is :obj:`sendSelectedValue` is true, and even then a label is translated only if an item with such a key is found in the dictionary; otherwise, label is written to :obj:`value` as it is. 
+   `control2attributeDict` (default: {})
+      A dictionary for translating the item's label into `value`. It is used only is `sendSelectedValue` is true, and even then a label is translated only if an item with such a key is found in the dictionary; otherwise, label is written to `value` as it is. 
 
-emptyString (default: "")
-Tells which combo box's item corresponds to an empty :obj:`value`. This is typically used when combo box's labels are attribute names and an item "(none)", which allows user to select no attribute. If we give :obj:`emptyString="(none)"`, :obj:`value` will be an empty string when the user selects "(none)". This is equivalent to specifying :obj:`control2attributeDict = {"(none)": ""}` (and is actually implemented like that), but far more convenient.
+   `emptyString` (default: "")
+      Tells which combo box's item corresponds to an empty `value`. This is typically used when combo box's labels are attribute names and an item "(none)", which allows user to select no attribute. If we give ``emptyString="(none)"``, `value` will be an empty string when the user selects "(none)". This is equivalent to specifying ``control2attributeDict={"(none)": ""}`` (and is actually implemented like that), but far more convenient.
 
-valueType (default: str or unicode)
-A function through which the currently selected item's label is converted prior to looking into :obj:`control2attributeDict`. Needed to convert Qt's QString.
+   `valueType` (default: str or unicode)
+      A function through which the currently selected item's label is converted prior to looking into `control2attributeDict`. Needed to convert Qt's QString.
 
 
 List Box
 sophisticated wrapper around QListBox. It's complexity arises from synchronization.
 
 
-listBox(widget, master, value, labels[, box, tooltip, callback, selectionMode])
+.. function:: listBox(widget, master, value, labels[, box, tooltip, callback, selectionMode])
 
-<dl class="attributes">
-value (required)
-The name of master's attribute containing indices of all selected values.
+   `value` (required)
+      The name of master's attribute containing indices of all selected values.
 
-labels (required)
-The name of master's attribute containing the list box's labels. Similar to :obj:`items` in combo box, list :obj:`labels` have one Orange-specific quirk: its element can be either a string, in which case it is used as a label, or a tuple, where the first element is a label name and the second can be either an icon on an integer, representing the attribute type which is used to create an icon. Most attribute lists in Orange Widgets are constructed this way.
+   `labels` (required)
+      The name of master's attribute containing the list box's labels. Similar to `items` in combo box, list `labels` have one Orange-specific quirk: its element can be either a string, in which case it is used as a label, or a tuple, where the first element is a label name and the second can be either an icon on an integer, representing the attribute type which is used to create an icon. Most attribute lists in Orange Widgets are constructed this way.
 
-selectionMode (default: QListWidget.SingleSelection)
-Tells whether the user can select a single item (:obj:`QListWidget.SingleSelection`), multiple items (:obj:`QListWidget.MultiSelection`, :obj:`QListWidget.ExtendedSelection`) or nothing (:obj:`QListWidget.NoSelection`).
+   `selectionMode` (default: QListWidget.SingleSelection)
+      Tells whether the user can select a single item (:obj:`QListWidget.SingleSelection`), multiple items (:obj:`QListWidget.MultiSelection`, :obj:`QListWidget.ExtendedSelection`) or nothing (:obj:`QListWidget.NoSelection`).
 
+   `value` is automatically cast to :obj:`OWGUI.ControlledList` (this is needed because the list should report any changes to the control, the list box; :obj:`OWGUI.ControlledList` is like an ordinary Python :obj:`list` except that it triggers synchronization with the list box at every change).
 
-:obj:`value` is automatically cast to :obj:`OWGUI.ControlledList` (this is needed because the list should report any changes to the control, the list box; :obj:`OWGUI.ControlledList` is like an ordinary Python :obj:`list` except that it triggers synchronization with the list box at every change).
+   `labels` is only partially synchronized with the list box: if a new list is assigning to `labels` attribute, the list will change. If elements of the existing list are changed or added, the list box won't budge. You should never change the list, but always assign a new list (or reassign the same after it's changed). If the labels are stored in ``self.listLabels`` and you write ``self.listLabels[1]="a new label"``, the list box won't change. To trigger the synchronization, you should continue by ``self.listLabels = self.listLabels``. This may seem awkward, but by our experience a list of selected items is seldom changed changed "per-item", so we were too lazy to write the annoyingly complex backward callbacks.
 
-:obj:`labels` is only partially synchronized with the list box: if a new list is assigning to :obj:`labels` attribute, the list will change. If elements of the existing list are changed or added, the list box won't budge. You should never change the list, but always assign a new list (or reassign the same after it's changed). If the labels are stored in :obj:`self.listLabels` and you write :obj:`self.listLabels[1]="a new label"`, the list box won't change. To trigger the synchronization, you should continue by :obj:`self.listLabels = self.listLabels`. This may seem awkward, but by our experience a list of selected items is seldom changed changed "per-item", so we were too lazy to write the annoyingly complex backward callbacks.
-
-<span>
-<span onclick="toggleVisibility(this);" class="hideshow">Show Example</span>
-<span class="hideshow"><a href="gui_listbox.py">Download example (gui_listbox.py)</a></span>
-<span class="hideshow"><a href="gui_listbox_attr.py">Download example (gui_listbox_attr.py)</a></span>
 
 
 Spin
 
 Spin control, a wrapper around QSpinBox.
 
-spin(widget, master, value, min, max[, step, box, label, labelWidth, orientation, tooltip, callback, controlWidth])
+.. function:: spin(widget, master, value, min, max[, step, box, label, labelWidth, orientation, tooltip, callback, controlWidth])
 
-
-min, max, step=1
-Minimal and maximal value, and step.
+   `min`, `max`, `step=1`
+      Minimal and maximal value, and step.
 
 
 Slider
 
 A wrapper around QSlider that allows user setting a numerical value between the given bounds.
 
-hSlider(widget, master, value[, box, minValue, maxValue, step, callback, labelFormat, ticks, divideFactor])
+.. function:: hSlider(widget, master, value[, box, minValue, maxValue, step, callback, labelFormat, ticks, divideFactor])
 
 
-minValue (default: 0), maxValue (default: 10), step (default: 1)
-Minimal and maximal value for the spin control, and its step.
+   `minValue` (default: 0), `maxValue` (default: 10), `step` (default: 1)
+      Minimal and maximal value for the spin control, and its step.
 
-ticks (default: 0)
-If non-zero, it gives the interval between two ticks. The ticks will appear below the groove.
+   `ticks` (default: 0)
+      If non-zero, it gives the interval between two ticks. The ticks will appear below the groove.
 
-labelFormat (default: " %d")
-Defines the look of the label on the righthand side of the slider. It has to contain one format character (like %d in the default), but can contain other text as well.
+   `labelFormat` (default: " %d")
+      Defines the look of the label on the righthand side of the slider. It has to contain one format character (like %d in the default), but can contain other text as well.
 
-divideFactor (default: 1.0)
-The value printed in the label is divided by :obj:`divideFactor`.
-
-
-For an example of usage, see the second example in the description of <a href="#labels-example">labels</a>.
+   `divideFactor` (default: 1.0)
+      The value printed in the label is divided by `divideFactor`.
 
 
 Check Box with Spin
 Check box with spin, or, essentially, a wrapper around
 OWGUI.checkBox and OWGUI.spin.
 
-checkWithSpin(widget, master, label, min, max, checked, value[, posttext, step, tooltip, checkCallback, spinCallback, labelWidth])
+.. function:: checkWithSpin(widget, master, label, min, max, checked, value[, posttext, step, tooltip, checkCallback, spinCallback, labelWidth])
 
-min, max, step (required)
-Minimal and maximal value for the spin control, and its step.
+   `min`, `max`, `step` (required)
+      Minimal and maximal value for the spin control, and its step.
 
-checked (required)
-Master's attribute that is synchronized with the state of the check box.
+   `checked` (required)
+      Master's attribute that is synchronized with the state of the check box.
 
-value (required)
-The attribute that is synchronized with the spin.
+   `value` (required)
+      The attribute that is synchronized with the spin.
 
-posttext (default: None)
-Text which appears on the right-hand side of the control.
+   `posttext` (default: None)
+      Text which appears on the right-hand side of the control.
 
-checkCallback (default: None), spinCallback (default: None)
-Function that are called when the state of the check box or spin changes.
+   `checkCallback` (default: None), `spinCallback` (default: None)
+      Function that are called when the state of the check box or spin changes.
 
 
 Labels
 ******
 
-There are two functions for constructing labels. The first is a simple wrapper around QLabel which differs only in allowing to specify a fixed width without needing an extra line. Note that unlike most other OWGUI widgets, this one does not have the argument :obj:`master`.
+There are two functions for constructing labels. The first is a simple wrapper around QLabel which differs only in allowing to specify a fixed width without needing an extra line. Note that unlike most other OWGUI widgets, this one does not have the argument `master`.
 
-widgetLabel(widget, label[, labelWidth])
+.. function:: widgetLabel(widget, label[, labelWidth])
 
-The second is a label which can synchronize with values of master widget's attributes.
+   The second is a label which can synchronize with values of master widget's attributes.
 
-label(widget, master, label[, labelWidth])
+.. function:: label(widget, master, label[, labelWidth])
 
-label
-:obj:`label` is a format string following Python's syntax (see the corresponding Python documentation): the label's content is rendered as :obj:`label % master.__dict__`.
+   `label`
+      `label` is a format string following Python's syntax (see the
+      corresponding Python documentation): the label's content is rendered as
+      ``label % master.__dict__``.
 
 
 *********
 **********
 
 
-widgetBox(widget, box=None, orientation='vertical', addSpace=False)
-Creates a box in which other widgets can be put. If :obj:`box` is given and not false, the box will be framed. If :obj:`box` is a string, it will be used for the box name (don't capitalize each word; spaces in front or after the string will be trimmed and replaced with a single space). Argument :obj:`orientation` can be :obj:`"vertical"` or :obj:`"horizontal"` (or :obj:`True` and :obj:`False`, or :obj:`1` and :obj:`0`, respectively).
+.. function:: widgetBox(widget, box=None, orientation='vertical', addSpace=False)
+
+   Creates a box in which other widgets can be put. If `box` is given
+   and not false, the box will be framed. If `box` is a string, it will
+   be used for the box name (don't capitalize each word; spaces in front or
+   after the string will be trimmed and replaced with a single space).
+   Argument `orientation` can be ``"vertical"`` or ``"horizontal"``
+   (or ``True`` and ``False``, or ``1`` and ``0``, respectively).
 
 
 Idented box
 ***********
 
 
-indentedBox(widget, sep=20)
-Creates an indented box. Widgets which are subsequently put into that box will be arranged vertically and aligned with an indentation of :obj:`sep`.
+.. function:: indentedBox(widget, sep=20)
+
+      Creates an indented box. Widgets which are subsequently put into
+      that box will be arranged vertically and aligned with an indentation
+      of `sep`.
 
 
 Inserting Space between Widgets
 *******************************
 
 Most widgets look better if we insert some vertical space between the controls
-or groups of controls. A few functions have an optional argument :obj:`addSpace`
+or groups of controls. A few functions have an optional argument `addSpace`
 by which we can request such space to be added. For other occasions, we can use
 the following two functions.
 
-separator(widget, width=0, height=8)
+.. function:: separator(widget, width=0, height=8)
 
-Function :obj:`separator` inserts a fixed amount of space into :obj:`widget`.
-Although the caller can specify the amount, leaving the default will help the
-widgets having uniform look.
+   Function `separator` inserts a fixed amount of space into `widget`.
+   Although the caller can specify the amount, leaving the default will help the
+   widgets having uniform look.
 
-rubber(widget[, orientation="vertical"])
+.. function:: rubber(widget[, orientation="vertical"])
 
-Similar to separator, except that the size is (1, 1) and that it expands in the
-specified direction if the widget is expanded. Most widgets should have rubber
-somewhere in their :obj:`controlArea`.
+   Similar to separator, except that the size is (1, 1) and that it expands in the
+   specified direction if the widget is expanded. Most widgets should have rubber
+   somewhere in their :obj:`controlArea`.
 
 Attribute Icons
 ***************
 
-getAttributeIcons()
+.. function:: getAttributeIcons()
 
-Returns a dictionary with attribute types (:obj:`orange.VarTypes.Discrete`,
-:obj:`orange.VarTypes.Continuous`, :obj:`orange.VarTypes.String`, -1) as keys
-and colored pixmaps as values. The dictionary can be used in list and combo
-boxes showing attributes for easier distinguishing between attributes of different types.
+   Returns a dictionary with attribute types (:obj:`orange.VarTypes.Discrete`,
+   :obj:`orange.VarTypes.Continuous`, :obj:`orange.VarTypes.String`, -1) as keys
+   and colored pixmaps as values. The dictionary can be used in list and combo
+   boxes showing attributes for easier distinguishing between attributes of different types.
 
 Send automatically / Send
 *************************
 
 Programming this into every widget is annoying and error-prone; at the time when the function described here was written, not many widgets actually did this properly.
 
-setStopper(master, sendButton, stopCheckbox, changedFlag, callback)
+.. function:: setStopper(master, sendButton, stopCheckbox, changedFlag, callback)
 
-sendButton
-The button that will be disabled when the check box is checked.
+   `sendButton`
+      The button that will be disabled when the check box is checked.
 
-stopCheckbox
-Check box that decides whether the changes are sent/commited/applied automatically.
+   `stopCheckbox`
+      Check box that decides whether the changes are sent/commited/applied automatically.
 
-changedFlag
-The name of the :obj:`master`'s attribute which tells whether there is a change which has not been sent/applied yet.
+   `changedFlag`
+      The name of the `master`'s attribute which tells whether there is a change which has not been sent/applied yet.
 
-callback
-The function that sends the data or applies the changes. This is typically the function which is also used as the :obj:`sendButton`'s callback.
+   `callback`
+      The function that sends the data or applies the changes. This is typically the function which is also used as the `sendButton`'s callback.
 
 
-:obj:`setStopper` is a trivial three lines long function which connects a few signals. Its true importance is in enforcing the correct procedure for implementing such button-check box combinations. Make sure to carefully observe and follow the example provided below.
+:obj:`setStopper` is a trivial three lines long function which connects a few signals. Its true importance is in enforcing the correct procedure for implementing such button-check box combinations.
 
+..
+   Make sure to carefully observe and follow the example provided below.
+
+   Missing, where did it go?
+

docs/extend-widgets/rst/plots.rst

 (:obj:`learner.color`). Who sets it and how? This we discuss in
 the following subsection.
 
-<h2>Colors in Orange Widgets</h2>
+************************
+Colors in Orange Widgets
+************************
 
 Uniform assignment of colors across different widget is an
 important issue. When we plot the same data in different widgets, we
                 self.graph.replot()
             l.isSelected = i in self.selectedLearners
 
-The complete code of this widget is available `here <OWLearningCurve_plot.py>`_.
+The complete code of this widget is available :download:`here <OWLearningCurve_plot.py>`.
 This is almost like a typical
 widget that is include in a standard Orange distribution, with a
 typical size just under 300 lines. Just some final cosmetics is needed

docs/extend-widgets/rst/plotsbasic.rst

 Running this example
 ********************
 
-You can find the full code for the example `here <owplot_example.py>`_.
+You can find the full code for the example :download:`here <owplot_example.py>`.
 This particular example has a timer, so that :obj:`set_data` is called every
 five seconds, and attributes are chosen at random each time, athough always 
 from the same data set. 

docs/extend-widgets/rst/progressbar.rst

 Class :obj:`OWWidget`, the mother class of all
 widgets, has for this purpose a set of functions, which include:
 
-<xmp class="code">
-progressBarInit()
-progressBarSet(value)
-progressBarFinished()
-</xmp>
+.. method:: progressBarInit()
+
+.. method:: progressBarSet(value)
+
+.. method:: progressBarFinished()
+
 
 where value is any number between 0 and 100. Sometimes, like it is
 the case for our widgets, we know about the number of iterations involved in

docs/extend-widgets/rst/settings.rst

         if self.commitOnChange:
             self.commit()
 
-You can now also inspect the `complete code <OWDataSamplerB.py>`_ of this
-widget. To distinguish it with a widget we have developed in the
-previous section, we have designed a special `icon <DataSamplerB.png>`_ for it. If you wish to test is
+You can now also inspect the :download:`complete code <OWDataSamplerB.py>`
+of this widget. To distinguish it with a widget we have developed in the
+previous section, we have designed a special
+:download:`icon <DataSamplerB.png>` for it. If you wish to test is
 widget in the Orange Canvas, put its code in the Test directory we
 have created for the previous widget, update the Canvas registry, and
 try it out using a schema with a File and Data Table widget.
 should be a corresponding widget's attribute recording the check box's
 state so that when the user changes a check box, the attribute changes
 and vice-versa. Although you can create such a link manually, you
-should always use the module <a href="owgui.htm">OWGUI</a> instead;
+should always use the module :doc:`OWGUI <owgui.rst>` instead;
 for instance, for a check box, use :obj:`OWGUI.checkBox` and not
 simply the Qt's :obj:`QCheckBox`.
 
 The settings fall into two groups. Some of them do not depend on
 the data, while other are context-dependent. For the first to be saved
 properly, you only need to list them in the :obj:`settingsList`
-in the widget definition, as already described <a
-href="settings.htm">elsewhere</a>.
+in the widget definition, as already described :doc:`elsewhere <settings.rst>`
 
 **************************
 Context dependent settings
 for the color since the attribute D is missing in the new data. Now
 comes the third data set, which only has attributes A, D and E. The
 context now can't be reused since the attribute used for the
-<em>required</em> :obj:`attrY` (the y axis) is missing.
+*required* :obj:`attrY` (the y axis) is missing.
 
 OK, now it is time to be a bit formal. As said,
 :obj:`contextHandlers` is a dictionary and the values in it need
 in the scatter plot, too.
 
 But the tuples are actually a shortcut for instances of
-:obj:`ContextField`. When you say :obj:`"attrX"` this is
-actually :obj:`ContextField("attrX",
-DomainContextHandler.Required)` (you should appreciate the
-shortcurt, right?). But see this monster from widget "Select
+:obj:`ContextField`. When you say :obj:`"attrX"` this is actually
+:obj:`ContextField("attrX", DomainContextHandler.Required)` (you should
+appreciate the shortcurt, right?). But see this monster from widget "Select
 Attributes" (file OWDataDomain.py)::
 
     contextHandlers = {"": DomainContextHandler("",
     ])}
 
 
-:obj:`ContextField`'s constructor gets the name and flags and a list of arguments that are written directly into the object instance. To follow the example, recall what Select Attributes looks like: it allows you to select a subset of attributes, the class attribute and the meta attributes that you want to use; the attributes in the corresponding three list boxes are stored in the widget's variables :obj:`chosenAttributes`, :obj:`classAttribute` and :obj:`metaAttributes` respectively. When the user selects some attributes in any of these boxes, the selection is stored in :obj:`selectedChosen`, :obj:`selectedClass` and <cose>selectedMeta</cose>. The remaining attributes - those that are not in any of these three list boxes - are in the leftover listbox on the left-hand side of the widget, and the content of the box is stored in the widget's variable :obj:`inputAttributes`.
+:obj:`ContextField`'s constructor gets the name and flags and a list of
+arguments that are written directly into the object instance. To follow the
+example, recall what Select Attributes looks like: it allows you to select a
+subset of attributes, the class attribute and the meta attributes that you
+want to use; the attributes in the corresponding three list boxes are stored
+in the widget's variables :obj:`chosenAttributes`, :obj:`classAttribute`
+and :obj:`metaAttributes` respectively. When the user selects some attributes
+in any of these boxes, the selection is stored in :obj:`selectedChosen`,
+:obj:`selectedClass` and :obj:`selectedMeta`. The remaining attributes
+- those that are not in any of these three list boxes - are in the leftover
+listbox on the left-hand side of the widget, and the content of the box is
+stored in the widget's variable :obj:`inputAttributes`.
 
-The above definition tells that the context needs to store the contents of the three list boxes by specifying the corresponding variables; the list of attributes is given as the name of the field and the list of selected attributes is in the optional named attribute :obj:`selected`. By :obj:`reservoir` we told the context handler that the attributes are taken from :obj:`inputAttributes`. So, when a context is retrieved, all the attributes that are not in any of the three list boxes are put into :obj:`inputAttributes`.
+The above definition tells that the context needs to store the contents of
+the three list boxes by specifying the corresponding variables; the list of
+attributes is given as the name of the field and the list of selected
+attributes is in the optional named attribute :obj:`selected`. By
+:obj:`reservoir` we told the context handler that the attributes are taken
+from :obj:`inputAttributes`. So, when a context is retrieved, all the
+attributes that are not in any of the three list boxes are put into
+:obj:`inputAttributes`.
 
-Why the mess? Couldn't we just store :obj:`inputAttributes` as the fourth list box? Imagine that the user first loads the data with attributes A, B, C, D, E and F, puts A, B, C in chosen and D in class. E and F are left in :obj:`inputAttributes`. Now she loads another data which has attributes A, B, C, D, E, and G. The contexts should match (the new data has all the attributes we need), but :obj:`inputAttributes` should now contain E and G, not E and F, since F doesn't exist any more, while G needs to be made available.
+Why the mess? Couldn't we just store :obj:`inputAttributes` as the fourth
+list box? Imagine that the user first loads the data with attributes A, B,
+C, D, E and F, puts A, B, C in chosen and D in class. E and F are left in
+:obj:`inputAttributes`. Now she loads another data which has attributes A,
+B, C, D, E, and G. The contexts should match (the new data has all the
+attributes we need), but :obj:`inputAttributes` should now contain E and
+G, not E and F, since F doesn't exist any more, while G needs to be made
+available.
 
-You can use :obj:`ContextField` (instead of tuples and strings) for declaring any fields, but you will usually need them only for lists or, maybe, some complicated future controls.
+You can use :obj:`ContextField` (instead of tuples and strings) for
+declaring any fields, but you will usually need them only for lists or,
+maybe, some complicated future controls.
 
 
 *****************************