From b2f0818c85b1fdfbe363701602960555bc233a44 Mon Sep 17 00:00:00 2001
From: Michael DM Dryden <mdryden@chem.utoronto.ca>
Date: Tue, 6 Jun 2017 15:35:46 -0400
Subject: [PATCH] Update README and CHANGELOG
---
CHANGELOG | 8 ++++-
README.markdown | 96 +++++++++++++++++++++----------------------------
2 files changed, 48 insertions(+), 56 deletions(-)
diff --git a/CHANGELOG b/CHANGELOG
index 0c5a35d..8dd9358 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,5 +1,11 @@
+Version 1.4
+ -Switched to GTK+3
+ -Support new DStat communications protocol (requires dstat-firmware>fe50c38)
+ -Many behind-the-scenes changes to improve code readability and make adding new experiment types easier
+ -Documented new Anaconda packages
+
Version 1.3.3
- -Bugfix #24: Remove ZODB support until it can be fixed for latest ZODB
+ -Bugfix #24: Remove ZODB support until it can be fixed for latest ZODB
Version 1.3.2
-Improves initial connection reliability
diff --git a/README.markdown b/README.markdown
index c428347..e47af15 100644
--- a/README.markdown
+++ b/README.markdown
@@ -9,90 +9,75 @@ It currently has no abilities for analyzing recorded data or opening previously
## Table of Contents:
1. [Installation](#Installation)
- 1. [Manual Install](#manual-install)
- 1. [pip Install](#pip-install)
+ 1. [MacOS](#macos)
+ 1. [Using Anaconda (Recommended)](#using-anaconda-recommended)
+ 2. [Old Homebrew Instructions](#old-homebrew-instructions)
+ 1. [Linux](#linux)
+ 2. [Windows](#windows)
2. [Getting Started](#Getting-Started)
# Introduction
The DStat interface is written primarily in Python and runs on Linux, Mac, and Windows.
It is the main method for running experiments on the DStat, controlling experimental parameters and collecting and plotting data.
-It currently has no abilities for analyzing recorded data or opening previously saved data files, but data is saved in a simple text format or numpy-compatible binary format and plots can be saved as images.
-
-*New in version 1.3:* dstat-interface can now save all data files to a ZODB database for later analysis.
-The old autosave functionality has still been retained.
+It currently has no abilities for analyzing recorded data or opening previously saved data files, but data is saved in a simple text format and plots can be saved as images.
# Installation
-Unfortunately, due to the python packages used, dstat-interface is difficult to make into a single self-contained package, so for the time being, the simplest way to run it is to install a python distribution. dstat-interface itself, therefore, requires no installation and can be run from any directory by executing `/dstat-interface/main.py` with python.
-
-## Manual Install
-Python and related packages needed: (versions listed are tested, older versions may still work)
+dstat-interface has moved to gtk+3 and we now recommend Anaconda/Miniconda for installation.
-* Python (2.7.9)
-* matplotlib (1.4.3—compiled with gtk backend)
-* numpy (1.9.2)
-* py2cairo (1.10.0)
-* pyserial (2.7)
-* pygtk (2.24.0)
-* pygobject (2.28.6)
-* XQuartz (2.7.7)
-* zeromq (4.0.5) and pyzmq (14.6.0)
-* pyyaml (3.11)
+## MacOS
+### Using Anaconda (Recommended)
-Optional:
+ 1. [Install Miniconda](https://repo.continuum.io/miniconda/Miniconda2-latest-MacOSX-x86_64.sh) It doesn't matter if you pick Python 2.7 or 3.5—this just sets Miniconda's default Python. (Skip if Miniconda or Anaconda are already installed)
+
+ 2. Create a new environment for dstat. In a terminal type:
+````conda create -n dstat -c mdryden python=2.7 dstat-interface dstat-interface-deps````
-* seaborn (0.7.0)—Makes prettier plots if available
+ 3. Then to run dstat-interface:
+ ````source activate dstat
+ python -m dstat_interface.main````
-### Mac OS X
+#### Old Homebrew Instructions
The easiest way to get most of the necessary requirements to run dstat-interface is using [Homebrew](http://brew.sh):
- brew tap homebrew/python
- brew update
- brew install python pygtk pygobject py2cairo zeromq
- brew install matplotlib --with-pygtk
+ brew tap homebrew/python
+ brew update
+ brew install python gobject-introspection gtk+3 pygobject3 py2cairo scipy zeromq
+ brew install matplotlib --with-pygtk
Be patient on the last step—matplotlib needs to be compiled and may take 2 or 3 minutes.
Make sure you're using brew-installed python, not OS X's default python. `which python` should point to `/usr/local/bin/python` not `/usr/bin/python`. Type `brew doctor` for more information if you are having issues.
-The interface runs in X11 using the GTK+ toolkit, so [XQuartz](http://xquartz.macosforge.org/landing/) needs to be installed.
-
The final requirements, can be installed using python's pip system:
- pip install pyserial pyzmq pyyaml seaborn
+ pip install pandas pyserial pyzmq pyyaml seaborn zmq-plugin
-### Linux
-Linux prerequisite installation is similar to that of Mac OS X, only using your distribution's native package manager rather than Homebrew, and X11 will likely be installed already. Some distributions may not have packages available for installing matplotlib or numpy, in which case, they should be installed using pip.
+## Linux
+Linux prerequisite installation is similar to that of MacOS with Homebrew, only using your distribution's native package manager rather than Homebrew, and X11 will likely be installed already. Some distributions may not have packages available for installing matplotlib or numpy, in which case, they should be installed using pip.
The final requirements, can be installed using python's pip system:
- pip install pyserial pyzmq pyyaml seaborn
-
-### Windows
-**These instructions are tricky on Windows, see the [pip install](#pip-install) below for an easier alternative.**
+ pip install pandas pyserial pyzmq pyyaml seaborn zmq-plugin
-While it is possible to install a bare python distribution and install the required prerequisites separately, [Python(x,y)](https://code.google.com/p/pythonxy/wiki/Downloads) has a python 2.7 distribution that already contains most of the necessary packages. However, pyserial is not installed in the recommended install so it should be manually selected or the full install done instead (tested with 2.7.9.0).
+## Windows
+The following terminal commands will result in a full installation of dstat-interface and its requirements, assuming [64-bit Miniconda][1] is installed:
-The newest versions of Python(x,y) are also missing PyGTK, so it should be installed from [here](http://ftp.gnome.org/pub/GNOME/binaries/win32/pygtk/2.24/pygtk-all-in-one-2.24.2.win32-py2.7.msi) once Python(x,y) is installed. Matplotlib should then be reinstalled to get gtk support from [here](https://downloads.sourceforge.net/project/matplotlib/matplotlib/matplotlib-1.4.3/windows/matplotlib-1.4.3.win32-py2.7.exe).
+````
+conda create -n dstat -c mdryden python=2 dstat-interface
+activate dstat
+````
-## pip Install
-Tagged git versions are uploaded to [PiPy](https://pypi.python.org/pypi/dstat-interface) regularly, and thus dstat-interface can be installed using the command `pip install dstat-interface`, which will attempt to automatically install matplotlib, numpy, pyserial, and pyzmq. (N.B. matplotlib does not install well with pip on Mac and should be manually installed with Homebrew as described above)
-This is still a bit experimental as pygtk and pygobject must be installed separately.
+To finish the installation, GTK+3 and its Python bindings must be installed:
-To launch a pip-installed dstat-interface, simply type:
-
- python -m dstat_interface.main
-
-into a terminal.
-
-### Windows
-The following terminal commands will result in a full installation of dstat-interface and its requirements, assuming [32-bit Miniconda][1] is installed:
-
- conda create -n dstat python pywin32
- activate dstat
- pip install --find-links http://192.99.4.95/wheels --trusted-host 192.99.4.95 scipy==0.17.0 pygtk2-win pycairo-gtk2-win dstat-interface
+ 1. Download the latest all-in-one installer from [here][2].
+
+ 2. When the installer prompts for the path to your Python distribution, navigate to your Miniconda/Anaconda envs folder and choose the dstat folder. If you chose to install Miniconda for your user only, the envs folder is found in `$USER/Miniconda2/envs` (for Miniconda) or `$USER/Anaconda/envs` (for Anaconda), where `$USER` is your user directory. If you installed Miniconda for all users, the Miniconda2/Anaconda folder will be in the root of your C: drive.
+
+ 3. When the installer asks which modules to install, choose GTK.
+
+ 4. Finish the installer.
-This makes use of pre-built binary wheels for many of the Windows packages, stored on our server.
We are installing in a separate environment to keep a clean system.
`activate dstat` will enter the environment (must be done whenever a new terminal is opened),
and `deactivate` will return to the root environment.
@@ -102,7 +87,8 @@ Therefore, to run dstat-interface from our environment, we must first activate i
activate dstat
python -m dstat_interface.main
-[1]: https://repo.continuum.io/miniconda/Miniconda2-latest-Windows-x86.exe
+[1]: https://repo.continuum.io/miniconda/Miniconda2-latest-Windows-x86_64.exe
+[2]: https://sourceforge.net/projects/pygobjectwin32/
# Getting started
## Interface overview
--
GitLab