Merge branch 'develop' into issue1124

Fixed Merge Conflicts in:
	src/sardana/macroserver/recorders/test/test_h5storage.py

CHANGELOG.md

@@ -7,6 +7,9 @@ This file follows the formats and conventions from [keepachangelog.com]
 
 ### Added
 
+* `shape` controller axis parameter (plugin), `shape` experimental channel
+  attribute (kernel) and `Shape` Tango attribute to the experimental channels
+  (#1296, #1466)
 * *scan information* and *scan point* forms to the *showscan online* widget (#1386, #1477, #1479)
 * `ScanPlotWidget`, `ScanPlotWindow`, `ScanInfoForm`, `ScanPointForm` and `ScanWindow`
   widget classes for easier composition of custom GUIs involving online scan plotting (#1386)
@@ -18,28 +21,55 @@ This file follows the formats and conventions from [keepachangelog.com]
 * Initial delay in position domain to the synchronization description
   in *ct* like continuous scans (#1428)
 * Avoid double printing of user units in PMTV: read widget and units widget (#1424)
+* Allowed hooks to macro description in Spock (#1523)
+* Assert motor sign is -1 or 1 (#1345, #1507)
+* Documentation on how to write 1D and 2D controllers (#1494)
+* Missing documentation of SEP18 concepts to how-to counter/timer controller (#995, #1492)
 * Document how to properly deal with exceptions in macros in order to not interfer 
   with macro stopping/aborting (#1461)
 * Documentation on how to start Tango servers on fixed IP - ORBendPoint (#1470)
 * Documentation example on how to more efficiently access Tango with PyTango
   in macros/controllers (#1456)
+* LICENSE file to python source distribution (#1490)
 
 ### Fixed
 
 * Execute per measurement preparation in `mesh` scan macro (#1437)
 * Continously read value references in hardware synchronized acquisition 
   instead of reading only at the end (#1442, #1448)
+* Ensure order of moveables is preserved in Motion object (#1505)
 * Avoid problems when defining different, e.g. shape, standard attributes,
   e.g. pseudo counter's value, in controllers (#1440, #1446)
+* Storing string values in PreScanSnapshot in NXscanH5_FileRecorder (#1486)
+* Storing string values as custom data in NXscanH5_FileRecorder (#1485)
+* Fill parent_macro in case of executing XML hooks e.g. in sequencer (#1497)
 * Problems with macro id's when `sequencer` executes from _plain text_ files (#1215, #1216)
 * `sequencer` loading of plain text sequences in spock syntax with macro functions (#1422)
 * Allow running Spock without Qt bindings (#1462, #1463)
+* Fix getting macroserver from remote door in Sardana-Taurus Door extension (#1506)
+* MacroServer opening empty environment files used with dumb backend (#1425, #1514, #1517, #1520)
+* Setting `Hookable.hooks` to empty list (#1522)
+* `Macro.hasResult()` and `Macro.hasParams()` what avoids adding empty _Parameters_ and _Result_
+  sections in the macro description in Spock (#1524)
+* Use equality instead of identity checks for numbers and strings (#1491)
+* Docstring of QtSpockWidget (#1484)
 * Recorders tests helpers (#1439)
 * Disable flake8 job in travis CI (#1455)
 * `createMacro()` and `prepareMacro()` docstring (#1460, #1444)
 * Make write of MeasurementGroup (Taurus extension) integration time more robust (#1473)
 * String formatting when rising exceptions in pseudomotors (#1469)
 
+### Changed
+
+* Experimental channel shape is now considered as a result of the configuration
+  and not part of the measurement group configuration (#1296, #1466)
+* Use `LatestDeviceImpl` (currently `Device_5Impl`) for as a base class of the Sardana Tango
+  devices (#1214, #1301, #1531)
+
+### Removed
+
+* `shape` from the measurement group configuration and `expconf` (#1296, #1466)
+
 ## [3.0.3] 2020-09-18
 
 ### Added

MANIFEST.in

@@ -12,3 +12,4 @@ exclude .ropeproject
 exclude build_*
 
 include CHANGELOG.md
+include LICENSE

doc/source/devel/api/sardana/pool/controller.rst

@@ -25,6 +25,7 @@
     :columns: 3
 
     * :class:`Readable`
+    * :class:`Referable`
     * :class:`Startable`
     * :class:`Stopable`
     * :class:`Loadable`
@@ -59,6 +60,17 @@ Readable interface
     :members:
     :undoc-members:
 
+Referable interface
+-------------------
+
+.. inheritance-diagram:: Referable
+    :parts: 1
+
+.. autoclass:: Referable
+    :show-inheritance:
+    :members:
+    :undoc-members:
+
 
 Startable interface
 -------------------

doc/source/devel/api/sardana/taurus/core/tango/sardana.rst

@@ -22,6 +22,7 @@
 
     pool <sardana/pool>
     macroserver <sardana/macroserver>
+    macro <sardana/macro>
 
 .. autofunction:: registerExtensions
 .. autofunction:: unregisterExtensions

doc/source/devel/api/sardana/taurus/core/tango/sardana/macro.rst

@@ -0,0 +1,37 @@
+.. currentmodule:: sardana.taurus.core.tango.sardana.macro
+
+
+:mod:`~sardana.taurus.core.tango.sardana.macro`
+===============================================
+
+.. automodule:: sardana.taurus.core.tango.sardana.macro
+
+.. rubric:: Classes
+
+.. hlist::
+    :columns: 4
+
+    * :class:`Macro`
+    * :class:`MacroInfo`
+
+Macro
+-----
+
+.. inheritance-diagram:: Macro
+    :parts: 1
+
+.. autoclass:: Macro
+    :show-inheritance:
+    :members:
+    :undoc-members:
+
+MacroInfo
+---------
+
+.. inheritance-diagram:: MacroInfo
+    :parts: 1
+
+.. autoclass:: MacroInfo
+    :show-inheritance:
+    :members:
+    :undoc-members:

doc/source/devel/guide_migration/2to3.rst

@@ -45,6 +45,10 @@ Sardana v3 was reduced by long time ago deprecated features. You can
 find a list of them together with the suggested substitutes in this
 `table <https://github.com/sardana-org/sardana/issues/1315>`_.
 
+For migrating the measurement group configurations (non-URI model names) you
+can use the `upgrade_mntgrp.py <https://github.com/sardana-org/sardana/blob/develop/scripts/upgrade/upgrade_mntgrp.py>`_
+script.
+
 
 
 

doc/source/devel/howto_controllers/howto_1dcontroller.rst

@@ -9,8 +9,125 @@ How to write a 1D controller
 The basics
 ----------
 
-.. todo:: document 1D controller howto
-
+This chapter provides the necessary information to write a one dimensional (1D)
+experimental channel controller in Sardana.
+
+.. contents:: Table of contents
+    :depth: 3
+    :backlinks: entry
+
+.. _sardana-1dcontroller-general-guide:
+
+General guide
+-------------
+
+:ref:`1D experimental channels <sardana-1d-overview>`
+together with :ref:`2D experimental channels <sardana-2d-overview>`
+and :ref:`counter/timers <sardana-countertimer-overview>`
+belong to the same family of *timerable* experimental channels.
+
+To write a 1D controller class you can follow
+the :ref:`sardana-countertimercontroller` guide keeping in mind
+differences explained in continuation.
+
+.. _sardana-1dcontroller-general-guide-shape:
+
+Get 1D shape
+~~~~~~~~~~~~
+
+1D controller should provide a shape of the spectrum which will be produced by
+acquisition. The shape can be either static e.g. defined by the detector's
+sensor size or dynamic e.g. depending on the detector's (or an intermediate
+control software layer e.g. `LImA`_) configuration like :term:`RoI` or binning.
+
+In any case you should provide the shape in the format of a one-element sequence
+with the length of the spectrum using
+the :meth:`~sardana.pool.controller.Controller.GetAxisPar` method.
+
+Here is an example of the possible implementation of
+:meth:`~sardana.pool.controller.Controller.GetAxisPar`:
+
+.. code-block:: python
+
+    class SpringfieldOneDController(TwoDController):
+
+        def GetAxisPar(self, axis, par):
+            if par == "shape":
+                return self.springfield.getShape(axis)
+
+For backwards compatibility, in case of not implementing the ``shape`` axis
+parameter, shape will be determined from the ``MaxDimSize`` of the ``Value``
+attribute, currently (4096,).
+
+.. _sardana-1dcontroller-differences-countertimer:
+
+Differences with counter/timer controller
+-----------------------------------------
+
+Class definition
+~~~~~~~~~~~~~~~~
+
+:ref:`The basics of the counter/timer controller <sardana-countertimercontroller-howto-basics>`
+chapter explains how to define the counter/timer controller class.
+Here you need to simply inherit from the
+`~sardana.pool.controller.OneDController` class:
+
+.. code-block:: python
+    :emphasize-lines: 3
+
+    from sardana.pool.controller import OneDController
+
+    class SpringfieldOneDController(OneDController):
+
+       def __init__(self, inst, props, *args, **kwargs):
+            super().__init__(inst, props, *args, **kwargs)
+
+.. _sardana-1dcontroller-getvalue:
+
+Get 1D value
+~~~~~~~~~~~~
+
+:ref:`Get counter value <sardana-countertimercontroller-howto-value>` chapter
+explains how to read a counter/timer value
+using the :meth:`~sardana.pool.controller.Readable.ReadOne` method.
+Here you need to implement the same method but its return value
+must be a one-dimensional `numpy.array` (or eventually
+a `~sardana.sardanavalue.SardanaValue` object) containing the spectrum instead
+of a scalar value.
+
+.. _sardana-1dcontroller-getvalues:
+
+Get 1D values
+~~~~~~~~~~~~~
+
+:ref:`Get counter values <sardana-countertimercontroller-howto-external-synchronization-get-values>`
+chapter explains how to read counter/timer values
+using the :meth:`~sardana.pool.controller.Readable.ReadOne` method while
+acquiring with external (hardware) synchronization.
+Here you need to implement the same method but its return value
+must be a sequence with one-dimensional `numpy.array` objects (or eventually
+with :obj:`~sardana.sardanavalue.SardanaValue` objects) containing spectrums
+instead of scalar values.
+
+Advanced topics
+---------------
+
+.. _sardana-1dcontroller-valuereferencing:
+
+Working with value referencing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1D experimental channels may produce significant arrays of data at high
+frame rate. Reading this data and storing it using sardana
+is not always optimal. `SEP2`_ introduced data saving duality, optionally,
+leaving the data storage at the responsibility of the detector
+(or an intermediate software layer e.g. `LImA`_). In this case sardana
+just deals with the reference to the data.
+
+Please refer to :ref:`sardana-2dcontroller-valuereferencing` chapter from
+:ref:`sardana-2dcontroller-howto` guide in order to implement this feature for 1D
+controller.
+
 .. _ALBA: http://www.cells.es/
 .. _ANKA: http://http://ankaweb.fzk.de/
 .. _ELETTRA: http://http://www.elettra.trieste.it/
@@ -35,3 +152,5 @@ The basics
 .. _numpy: http://numpy.scipy.org/
 .. _SPEC: http://www.certif.com/
 .. _EPICS: http://www.aps.anl.gov/epics/
+.. _SEP2: http://www.sardana-controls.org/sep/?SEP2.md
+.. _LImA: https://lima1.readthedocs.io/en/latest/