[mask] minor mask improvements

[PiRK]

Adds resetSelectionMask to dock widget API.

Fixes also a few minor sphinx warnings.

EDIT: Initially this PR was meant to close #834, but this will need a bit more work than expected.

[PiRK]

Fixing #834 seems to cause unexpected side effects when the empty mask is saved to the mask history stack, so I reverted the initial commit and I'll fix the issue directly in PyMca by avoiding calling setSelectionMask with an empty array.

This PR is now just a minor docstring improvement and exposes resetSelectionStack in the dock widget.

[PiRK]

Would it be OK to set self._z = self.plot.getActiveImage().getZLayer() + 1 in MaskToolsWidget?

I have a case for which my active image is on z=1, and when it is changed while the mask widget is hidden, the image is redrawn on top of the mask, which is then invisible (vasole/pymca#58 (comment))

[vasole]

@t20100

It would be better than to have something hard coded to 1. I would say proposed solution should be the default for the case the application has not explicitly set it.

In any case, an application should be able to specify at what level/layer wants the mask.

[t20100]

+1 for what @PiRK proposed and optionally to set the Z value of the mask.

[PiRK]

After looking at the code, tt seems self._z = activeImage.getZValue() + 1 is already implemented in the _activeImageChanged and _activeImageChangedAfterCare slots.

The issue only exists when the mask is set while the mask widget has never been set visible, so neither one of these slots is connected, and the Z layer is set to its init value (1). I will assess whether it is possible to connect _activeImageChangedAfterCare already in __init__ .

[PiRK]

Actually it would not help to have the slot connected in init, because _activeImageChangedAfterCare would automatically disconnect itself as soon as the active image is set with a different shape as the current mask (initialized as a (0, 0) shape array).

The broader question is whether we want to change the mask widget to have the same behavior whether is is hidden or shown, or keep it as it is. As it is, it's designed to fully work and accept image changes only when visible. When hidden, it only shows the mask as long as the shape of the active image does not change, else it removes the mask and disconnects itself.

[t20100]

The mask widget was only designed to work with an active image.
It's already be extended to scatter plots and is not ready for synchronization with other mask widgets...
It's probably time to consider a refactoring.

[vasole]

The synchronization can be achieved by the application as being shown with the work on PyMca.

Can this PR be merged?