Merge pull request #1150 from sardana-org/release-Jul19

Release jul19

.bumpversion.cfg

@@ -3,7 +3,7 @@ commit = True
 message = Bump version {current_version} to {new_version}
 tag = False
 tag_name = {new_version}
-current_version = 2.7.2
+current_version = 2.8.0
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\-(?P<release>[a-z]+))?
 serialize = 
 	{major}.{minor}.{patch}-{release}

.gitignore

@@ -2,5 +2,6 @@
 /dist
 /build
 /setup.cfg
+/src/sardana.egg-info
 *.pyc
 .idea/

.travis.yml

@@ -73,3 +73,14 @@ doctr:
   require-master: false
   sync: true
   built-docs: build/sphinx/html/
+
+deploy:
+  # deploy to pypi when a version tag is pushed to the official repo
+  - provider: pypi
+    user: sardana_bot
+    password:
+      secure: "HvZGtw8qFlacssi7FE92+gFgQPRRPvurpPxi/Gq74TeKWU0X4EbWVT3XMdi7sb7yA7JQlOGIGtY3ofzEdrKgKcEsrxxKbeSW7foDf3+AlmMF7c31ePxkqBCGMSAxsaCjKJR2sVtBNiycp0I7LWYeKlzFNY2W8aZW9dnpkC9aD/oGdNRJlCVGq912xaTnXRxmUrh+2IeUqsXKqfih7E0Qw99VXOLFdHIHtoPGN5ka+tvLp+zNFMi1q2HUyix4P/aQ10BwE5t1onfdSBBh7bzZTINoUVuN1bstNXYcoqfVMAbOoeArIIr7z41eYd8G8WMTXJp2MFrO61AW6xK8htB07RX2eaEWq7KT4zazG5vP/Skayr7ofnB/d3Rs1BOre9ttScJIxwyQLhL60WeM9NyCoHVjNdKYK5gNHX4se/6FOzmHm1VgQgI9bzyfIIAoSSyUL/5KOGdOwhMPSij5AT1YIy8RSe7efm+xw3md+wcmEsbaMX9VEy2YgTL0/nmFHrEA+9HV0I5xkFBQ8BHuK0YFubQ9rG99B1GwF0Vl85M+Ylp5D1/p70sXCHEUk3SbOcg9Kz0TTisDMuDT2ajJYGylg7/OskI5OwOBbEndP8OUPesm62V1ciQcKjH2L81yWajRPSfd/OPjoMwG+XdaG5rR7m2FACXvyhEOIeK1Mt41MvM="
+    on:
+      repo: sardana-org/sardana
+      tags: true
+      condition: "$TRAVIS_TAG =~ ^[0-9]+.[0-9]+.[0-9]+$"

CHANGELOG.md

@@ -5,6 +5,93 @@ This file follows the formats and conventions from [keepachangelog.com]
 
 ## [Unreleased]
 
+## [2.8.0] 2019-07-01
+
+### Added
+
+* SEP2 - Improve integration of 1D and 2D experimental channels (#775):
+  * Possibility to report acquisition results in form of value references (in 
+  the URI format) of 1D and 2D experimental channels:
+    * `Referable` base class to inherit from when developing a controller 
+    plugin
+    * `ValueRef` and `ValueRefBuffer` Tango attributes and `value_ref` and 
+    `value_ref_buffer` core attributes to propagate value references 
+    proceeding from the controllers.
+  * Possibility to configure value referencing from the measurement group level
+    (_Ref Enabled_ and _Ref Pattern_ columns in expconf and 
+    `value_ref_pattern` and `value_ref_enabled` configuration parameters) or
+    a single channel level (`ValueRefPattern` and `ValueRefEnabled` Tango 
+    attributes) which both reach the controller plugin as axis parameters 
+    `value_ref_pattern` and `value_ref_enabled`.
+  * Creation of Virtual Data Sets (VDS) for value references of _h5file_ scheme
+    in HDF5 file recorder.
+  * Possibility to still use pseudo counters based on 1D and 2D experimental
+    channels when value referencing is in use.
+  * Possibility to include 2D experimental channels in continuous acquisition
+    using value reporting (`ValueBuffer` Tango attribute to 2DExpChannel and
+    `value_buffer` core attribute)
+  * `VALUE_BUFFER_CODEC` and `VALUE_REF_BUFFER_CODEC` to sardanacustomsettings.
+* Reintroduce `showscan online` to spock (#1042)
+* Full support to *spock syntax* in loading sequences from files (#645, #672)
+* Info in `lsmac` output about macros being overridden (#930, #947)
+* Allow to configure timeout on pool element's (Taurus extensions) *go* methods e.g.
+  `move`, `count`, etc. (#992)
+* Emulated hardware triggering between dummy counter/timer and trigger/gate elements
+  (#1100)
+* Macro example demonstrating how to add an extra scan column with motor
+  positions shifted to the middle of the scan interval: `ascanct_midtrigger`
+  (#1105)
+* Support to 7 axes geometry in `pa` macro (#1116)
+* Protection to `showscan` when a non HDF5 file is getting opened (#1073)
+* Auto-deploy to PyPI with Travis (#1113)
+* Print output of `send2ctrl` macro only if it contains something (#1120)
+* Add `DescriptionLength` view option for adjusting the `lsdef` macro description
+  (#1107, #1108)
+* Add `ShowScanOnline` component to Taurus Qt extensions (#1042)
+
+### Changed
+
+* `Data` Tango attribute of experimental channels (CTExpChannel,
+  ZeroDExpChannel, OneDExpChannel, PseudoCounter) to `ValueBuffer` (SEP2, #775)
+* Value buffer data structure format from `{"index": seq<int>, "data": seq<str>}`
+  to `{"index": seq<int>, "value": seq<str>}` (SEP2, #775)
+* Default encoding of `ValueBuffer` and `ValueRefBuffer` attributes (SEP2, #775)
+  from JSON to pickle
+* Mapping of Integer data type to Tango DevLong64 (#1083)
+
+### Fixed
+
+* Hanging scans by avoiding deepcopy of `DeviceProxy` (#1102)
+* Restore motor parameters (vel, acc, dec) before going to start position in dNscact
+  macros (#1085)
+* Calculation of nb_starts argument of `PrepareOne` method of timerable controllers
+  when software synchronization is in use (#1110)
+* Interactive macros on Windows (#347)
+* expconf when empty (unspecified) DataType (#1076)
+* Output block of scan records which do not fit the console width (#924)
+* Fix bug on exception popups in macroexecutor (#1079, #1088)
+* Cyclic references between scan macros and GSF internals (#816, #1115)
+* Enable expconf buttons (Reload and Apply) when local configuration was kept after
+  receiving external changes (#959, #1093)
+* Avoid external changes pop-up when synchronizer is changed in the expconf by
+  removing global measurement group synchronizer (#1103)
+* Show external changes pop-up in expconf when last measurement group is deleted
+  remotelly (#1099)
+* Pop-up message when expconf configuration changed externally (#1094)
+* Remove circlular references between the macro object and the FIO recorder (#1121)
+
+### Deprecated
+
+* Datasource Tango attribute, data_source core attributes and data_source
+1D and 2D controller axis parameter (SEP2, #775).
+
+### Removed
+
+* `ValueBuffer` Tango attribute of 0D exp. channels deprecated in version
+2.3.0. `AccumulationBuffer` attribute serves for the same need (SEP2, #775).
+Exceptionally no major version bump is done cause it seems like this attribute
+was not used programmatically in third party plugins/GUIs. 
+
 ## [2.7.2] 2019-05-28
 
 ### Fixed
@@ -29,20 +116,28 @@ of the synchronization types: trigger, gate and start (#1090)
 ### Added
 
 * Possibility to directly acquire an experimental channel (without the need to define
-  a measurement group) (#185, #997)
+  a measurement group) (#185, #997, #1048, #1061)
   * `IntegrationTime` (Tango) and `integration_time` (core) attributes to all experimental
     channels
   * `Timer` (Tango) and `timer` (core) attribute to all timerable experimental channels
   * `default_timer` class attribute to all timerable controllers (plugins) to let them
     announce the default timer axis
+* Possibility to pass an experimental channel (now compatible only with timerable channels) 
+  as a parameter of `ct` and `uct` macros in order to acquire directly on the channel (#1049)
+* `Countable` element type that includes measurement group and experimental channels (#1049)
 * `newfile` macro for setting `ScanDir`, `ScanFile` and `ScanID` env variables (#777)
+* Warning message when hooks gets overridden with `Hookable.hooks` property (#1041)
+* Acquisition macro examples (#1047)
 
 ### Fixed
 
 * `expconf` warns only about the following environment variables changes: `ScanFile`,
   `ScanDir`, `ActiveMntGrp`, `PreScanSnapshot` and `DataCompressionRank` (#1040)
 * MeasurementGroup's Moveable attribute when set to "None" in Tango is used as None
   in the core (#1001)
+* Compatibility of measurement group plotting configurations created with
+  sardana < 2.4.0 and taurus < 4.3.0 (#1017, #1022)
+* General Hook tests (#1062)
 
 ## [2.6.1] 2019-02-04
 
@@ -608,7 +703,8 @@ Main improvements since sardana 1.5.0 (aka Jan15):
 
 
 [keepachangelog.com]: http://keepachangelog.com
-[Unreleased]: https://github.com/sardana-org/sardana/compare/2.7.2...HEAD
+[Unreleased]: https://github.com/sardana-org/sardana/compare/2.8.0...HEAD
+[2.8.0]: https://github.com/sardana-org/sardana/compare/2.8.0...2.7.2
 [2.7.2]: https://github.com/sardana-org/sardana/compare/2.7.1...2.7.2
 [2.7.1]: https://github.com/sardana-org/sardana/compare/2.7.0...2.7.1
 [2.7.0]: https://github.com/sardana-org/sardana/compare/2.6.1...2.7.0

CONTRIBUTING.md

@@ -12,63 +12,168 @@ In this model, there are two long-lived branches:
 
 For the contributions, we use the [Fork & Pull Model][]:
 
-1. the contributor first [forks][] the official sardana repository
-2. the contributor commits changes to a branch based on the 
+1. The contributor first [forks][] the official sardana repository
+2. The contributor commits change to a branch based on the 
    `develop` branch and pushes it to the forked repository.
-3. the contributor creates a [Pull Request][] against the `develop` 
+3. The contributor creates a [Pull Request][] (PR) against the `develop` 
    branch of the official sardana repository.
-4. anybody interested may review and comment on the Pull Request, and 
-   suggest changes to it (even doing Pull Requests against the Pull
-   Request branch). At this point more changes can be committed on the 
+4. Anybody interested may review and comment on the PR, and 
+   suggest changes to it (even doing PRs against the PR branch).
+   At this point more changes can be committed on the 
    requestor's branch until the result is satisfactory.
-5. once the proposed code is considered ready by an appointed sardana 
-   integrator, the integrator merges the pull request into `develop`.
-
-
-## Important considerations:
+5. Once the proposed code is considered ready by an appointed sardana 
+   integrator, the integrator merges the PR into `develop`.
 
-In general, the contributions to sardana should consider following:
+## Notes:
+
+- These contribution guidelines are very similar but not identical to 
+  those for the [GithubFlow][] workflow. Basically, most of the 
+  GitHubFlow recommends can be applied for Sardana except that the 
+  role of the `master` branch in GithubFlow is done by `develop` in our 
+  case. 
+
+- If the contributor wants to explicitly draw the attention of some 
+  specific person to the review process, [mentions][] can be used
+
+- If a pull request (or a specific commit) fixes an open issue, the pull
+  request (or commit) message may contain a `Fix #N` tag (N being 
+  the number of the issue) which will automatically [close the related 
+  issue][tag_issue_closing]
 
-- The code must comply with the [Sardana coding conventions][].
-  [Sardana travis-ci][] will check it for each Pull Request (PR) using
-  the latest version of [flake8 available on PyPI][]. The check
-  will be done just on this part of code that is modified by the PR
-  together with some lines of context.
-  In case the check fails, please correct the errors and commit
-  to the PR branch again. You may consider running the check locally
-  using the [flake8_diff.sh][] script in order to avoid unnecessary commits.
-  If you find problems with fixing these errors do not hesitate to ask for
-  help in the PR conversation! We will not reject any contribution due
-  to these errors - the purpose of this check is just to maintain the code
-  base clean.
+# Coding conventions:
+
+In general, the contributions to Sardana should consider following:
+
+- The code must comply with the sardana coding conventions:
+  - We try to follow the standard Python style conventions as
+    described in [Style Guide for Python Code](http://www.python.org/peps/pep-0008.html)
+  - Code **must** be python 2.6 compatible
+  - Use 4 spaces for indentation
+  - use ``lowercase`` for module names. If possible prefix module names with the
+    word ``sardana`` (like :file:`sardanautil.py`) to avoid import mistakes.
+  - use ``CamelCase`` for class names
+  - "shebang line" should be the first line of a python module 
+    ```
+    #!/usr/bin/env python
+    ```
+  - python module should contain license information (see template below)
+  - avoid populate namespace by making private definitions private (``__`` prefix)
+    or/and implementing ``__all__`` (see template below)
+  - whenever a python module can be executed from the command line, it should 
+    contain a ``main`` function and a call to it in a ``if __name__ == "__main__"``
+    like statement (see template below)
+  - document all code using [Sphinx][] extension to [reStructuredText]{}
 
 - The contributor must be clearly identified. The commit author 
   email should be valid and usable for contacting him/her.
 
 - Commit messages  should follow the [commit message guidelines][]. 
   Contributions may be rejected if their commit messages are poor.
-  
+
 - The licensing terms for the contributed code must be compatible 
   with (and preferably the same as) the license chosen for the Sardana 
   project (at the time of writing this file, it is the [LGPL][], 
   version 3 *or later*).
 
-
-## Notes:
-
-- These contribution guidelines are very similar but not identical to 
-  those for the [GithubFlow][] workflow. Basically, most of what the 
-  GitHubFlow recommends can be applied for Sardana except that the 
-  role of the `master` branch in GithubFlow is done by `develop` in our 
-  case. 
-
-- If the contributor wants to explicitly bring the attention of some 
-  specific person to the review process, [mentions][] can be used
-
-- If a pull request (or a specific commit) fixes an open issue, the pull
-  request (or commit) message may contain a `Fixes #N` tag (N being 
-  the number of the issue) which will automatically [close the related 
-  Issue][tag_issue_closing]
+The following code can be used as a template for writing new python modules to
+Sardana:
+
+```python
+    #!/usr/bin/env python
+    # -*- coding: utf-8 -*-
+
+    ##############################################################################
+    ##
+    ## This file is part of Sardana
+    ## 
+    ## http://www.tango-controls.org/static/sardana/latest/doc/html/index.html
+    ##
+    ## Copyright 2019 CELLS / ALBA Synchrotron, Bellaterra, Spain
+    ## 
+    ## Sardana is free software: you can redistribute it and/or modify
+    ## it under the terms of the GNU Lesser General Public License as published by
+    ## the Free Software Foundation, either version 3 of the License, or
+    ## (at your option) any later version.
+    ## 
+    ## Sardana is distributed in the hope that it will be useful,
+    ## but WITHOUT ANY WARRANTY; without even the implied warranty of
+    ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    ## GNU Lesser General Public License for more details.
+    ## 
+    ## You should have received a copy of the GNU Lesser General Public License
+    ## along with Sardana.  If not, see <http://www.gnu.org/licenses/>.
+    ##
+    ##############################################################################
+
+    """A :mod:`sardana` module written for template purposes only"""
+
+    __all__ = ["SardanaDemo"]
+    
+    __docformat__ = "restructuredtext"
+    
+    class SardanaDemo(object):
+        """This class is written for template purposes only"""
+        
+    def main():
+        print "SardanaDemo"s
+    
+    if __name__ == "__main__":
+        main()
+```
+
+# Documentation Style Guide
+
+- All standalone documentation should be written in plain text (``.rst``) files
+  using [reStructuredText][] for markup and formatting. All such
+  documentation should be placed in directory `doc/source` of the Sardana
+  source tree. The documentation in this location will serve as the main source
+  for Sardana documentation and all existing documentation should be converted
+  to this format.
+- **Up to which level we will guarantee the documentation to be addressable?** 
+   We guarantee up to three levels of the documentation chapters to be addressable.
+   For example: Sardana Documentation (level 1) -> Developer's Guide (level 2) -> Writing macros (level 3)
+- **How to document Tango specific interfaces/implementation?**
+   Sardana documentation should be as much as possible Control System (server layer) agnostic.
+   In general, only the Tango API should contain Tango interfaces explanation.
+- **How to refer to Sardana and its elements**
+   We use the following names:
+   * Sardana - Sardana project
+   * Sardana server - Sardana server
+   * Device Pool - Pool of devices
+   * Pool server - Device Pool server process
+   * MacroServer - Environment where macros are defined and Macro execution contexts resides 
+   * MacroServer server - MacroServer server process
+   * macro - user procedure
+   * Spock - Sardana CLI
+- **Which writing style should I use?**
+   We suggest to use the second person writing style, for example:
+   "In order to stop the macro you need to press Ctrl+C".
+
+# Continuous Integration
+
+We practice Continuous Integration (CI) in the Sardana project for any PR or direct
+push to its `master` or `develop` branches. At the time of writing this guide this
+includes the following jobs:
+
+- [Sardana tests](https://sardana-controls.org/devel/howto_test/index.html)
+  run, at least, on the current Debian stable release will be executed by [Sardana travis-ci][].
+  You may use [sardana-test Docker container](https://hub.docker.com/r/reszelaz/sardana-test)
+
+- [Sardana travis-ci][] will check it for each Pull Request (PR) using
+  the latest version of [flake8 available on PyPI][]. The check
+  will be done just on this part of code that is modified by the PR
+  together with some lines of context.
+  In case the check fails, please correct the errors and commit
+  to the PR branch again. You may consider running the check locally
+  using the [flake8_diff.sh][] script in order to avoid unnecessary commits.
+
+- [Sardana travis-ci][] will build the documentation and publish it on GitHubPages:
+  [](www.sardana-controls.org) and check if there are any [Sphinx][]
+  build warnings.
+
+Failure of any of the above jobs will give information to the sardana integrtors that your
+PR is not ready for review. If you find problems with fixing these errors do not hesitate to ask for
+help in the PR conversation!
 
 
 [gitflow]: http://nvie.com/posts/a-successful-git-branching-model/
@@ -79,8 +184,10 @@ In general, the contributions to sardana should consider following:
 [GitHubFlow]: https://guides.github.com/introduction/flow/index.html
 [mentions]: https://github.com/blog/821-mention-somebody-they-re-notified
 [tag_issue_closing]: https://help.github.com/articles/closing-issues-via-commit-messages/
-[Sardana coding conventions]: http://www.sardana-controls.org/devel/guide_coding.html
+[Sardana]: http://www.sardana-controls.org
 [LGPL]: http://www.gnu.org/licenses/lgpl.html
 [Sardana travis-ci]: https://travis-ci.org/sardana-org/sardana
 [flake8_diff.sh]: https://github.com/sardana-org/sardana/blob/develop/ci/flake8_diff.sh
 [flake8 available on PyPI]: https://pypi.org/project/flake8
+[Sphinx]: http://www.sphinx-doc.org
+[reStructuredText]: http://docutils.sourceforge.net/rst.html