Updated documentation. Included brief instrumentation guide.

.travis.yaml

@@ -1,7 +1,7 @@
 language: python
 python:
-  - "3.0"
+  - "3.5"
 install:
-  - "pip install -r requirements.txt"
+  - "pip3 install -r requirements.txt"
 script:
-  - python setup.py develop test
+  - python3 setup.py develop test

AUTHORS.txt → AUTHORS

@@ -1,8 +1,8 @@
 UserAle.pyqt5 is written and maintained by Michelle Beard and 
 various contributors:
 
-Development Leads
-`````````````````
+Development Lead
+````````````````
 
 - Michelle Beard <mbeard@draper.com>
 

MANIFEST.in

@@ -1,5 +1,6 @@
 include MANIFEST.in
 include setup.py
-include README.txt 
-include CHANGELOG.txt 
-include LICENSE.txt
+include README
+include AUTHORS
+include CHANGELOG
+include LICENSE

README

@@ -0,0 +1,8 @@
+UserAle
+=======
+
+UserAle.pyqt5 is one of the Software As A Sensor™ products. The goal of Software As A Sensor™ is to develop understanding 
+of your users through their interactions with your software product. You can then apply that understanding to improve your 
+product's design and funtionality. UserAle.pyqt5 provides an easy way to generate highly detailed log streams from an PyQT5 application.
+
+UserAle.pyqt5 is developed at Draper and released free and open source through the Apache v2.0 license. Bug reports and contributions are welcome through Github.

docs/source/authors.rst

@@ -1,4 +1,4 @@
 Authors
 -------
 
-.. include:: ../../AUTHORS.txt
+.. include:: ../../AUTHORS

docs/source/changelog.rst

@@ -3,4 +3,4 @@ UserAle Changelog
 
 Here you can see the full list of changes between each UserAle.pyqt5 release.
 
-.. include:: ../../CHANGELOG.txt
+.. include:: ../../CHANGELOG

docs/source/conf.py

@@ -52,8 +52,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Apache UserAle'
-copyright = u'2016, The Charles Stark Draper Laboratory Licensed under Apache Software License.'
+project = u'UserAle'
+copyright = u'2016, The Charles Stark Draper Laboratory.'
 author = u'Michelle Beard <mbeard@draper.com>'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -168,16 +168,16 @@
 #html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_domain_indices = True
+html_domain_indices = False
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #html_show_sphinx = True

docs/source/contents.rst.inc

@@ -10,7 +10,7 @@ User's Guide
 API Reference
 -------------
 
-This entire section is mainly for Developers of UserAle. This section was automatically generated by `Sphinx <http://www.sphinx-doc.org/en/stable/>`_ and `apidoc <http://apidocjs.com/>`_. 
+This entire section is mainly for developers of UserAle. This section was automatically generated by `Sphinx <http://www.sphinx-doc.org/en/stable/>`_ and `apidoc <http://apidocjs.com/>`_. 
 
 .. toctree::
    :maxdepth: 3

docs/source/index.rst

@@ -1,14 +1,5 @@
 :orphan:
 
-Apache UserAle's documentation!
-===============================
+.. include:: ../../README
 
 .. include:: contents.rst.inc
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

docs/source/installation.rst

@@ -2,3 +2,113 @@
 
 Installation Guide
 ==================
+
+Requirements
+------------
+
+* Python 3.5 or above
+* PyQt5, version 5.3 or above
+* pip3, see requirements.txt
+
+Installing UserAle
+------------------
+
+The first step is to install UserAle. First, checkout the latest version of UserAle from our Github repository.
+
+::
+
+	$ git clone https://github.com/draperlaboratory/userale.pyqt5.git
+
+UserAle is a python3 project, so it can be installed like any other python library. Several operating systems (Mac OS X, Major Versions of Linux/BSD) have Python3 pre-installed, so you should just have to run
+
+::
+	
+    $ easy_install3 userale
+
+or
+
+::
+
+    $ pip3 install userale
+
+Users are strongly recommended to install UserAle in a virtualenv. Instructions to setup an virtual environment will be explained below.
+
+.. note ::
+
+	UserAle.pyqt5 requires that PyQt5 and the Qt5 bindings has been installed. Instructions to install PyQt5 and Qt5 in a virtual environment will be left to the user.
+	
+.. note ::
+
+	When the package is installed via ``easy_install3`` or ``pip3`` this function will be bound to the ``userale`` executable in the Python installation's ``bin`` directory (on Windows - the ``Scripts`` directory).
+
+Installing UserAle in an Virtual Environment
+--------------------------------------------
+
+There are multiple ways to create virtual environments for a Python3 application. virtualenv is a one of those tools to create isolated Python environments. virtualenv creates a folder which contains all the necessary executables to use the packages that the UserAle project would need. 
+
+
+Start by changing directory into the root of UserAle's project directory, and then use the virtualenv command-line tool to create a new environment:
+
+::
+	
+	$ virtualenv --python=/usr/bin/python3 env
+
+
+Optionally, Python3 has built in support for virtual environments. 
+
+::
+
+	$ mkdir env 
+	$ python3 -m venv env
+
+Activate environment:
+
+::
+
+	$ source env/bin/activate
+
+Install UserAle requirements:
+
+::
+
+	$ env/bin/pip3 -r requirements.txt
+
+To build the source code and run all unit tests.
+
+::
+
+    $ env/bin/python3 setup.py develop test
+
+Deactivate environment
+
+:: 	
+
+	$ deactivate
+
+Installing Documentation 
+------------------------
+
+To save yourself the trouble, all up to date documentation is available at https://draperlaboratory.github.io/userale.pyqt5/.
+
+However, if you want to manully build the documentation, the instructions are below.
+
+To build UserAle's documentation, create a directory at the root level of ``/userale.pyqt5`` called userale.pyqt5-docs.
+
+::
+
+	$ mkdir userale.pyqt5-docs & cd userale.pyqt5/docs
+
+Execute build command:
+
+::
+
+	# Inside top-level docs/ directory.
+ 	$ make html
+
+This should build the documentation in your shell, and output HTML. At then end, it should say something about documents being ready in ``userale.pyqt5-docs/html``. 
+
+You can now open them in your browser by typing
+
+::
+
+	$ open userale.pyqt5-docs/html/index.html

docs/source/quickstart.rst

@@ -1,4 +1,58 @@
 .. _quickstart:
 
 Quickstart Guide
-================
+================
+
+Instrumenting Your Application with UserAle
+-------------------------------------------
+
+It's very simple to instrument a PyQ5 application with UserAle. Simply import the UserAle library and register it with your application. 
+
+Below is an example PyQt5 application taken from ZetCode PyQt5 tutorial instrumented with UserAle
+
+::
+
+	import sys
+	from PyQt5.QtWidgets import QWidget, QLabel, QPushButton, QApplication, QMessageBox
+	from PyQt5.QtCore import QCoreApplication, QObject, QEvent
+
+	from userale.ale import Ale
+
+	class TestApplication (QWidget):
+	    
+	    def __init__(self):
+	        super().__init__()
+	        self.initUI()
+	        
+	    def initUI(self):               
+	        qbtn = QPushButton('Quit', self)
+	        qbtn.setObjectName ("testApplicationButton")
+	        qbtn.clicked.connect(QCoreApplication.instance().quit)
+	        qbtn.resize(qbtn.sizeHint())
+	        qbtn.move(50, 50)       
+	         
+	        self.setGeometry(300, 300, 250, 150)
+	        self.setWindowTitle('Quit button')    
+	        self.show()
+	        
+	if __name__ == '__main__':
+	    app = QApplication(sys.argv)    
+	    ex = TestApplication()
+	    # Initiate UserAle
+	    ale = Ale ()
+	    # install globally
+	    app.installEventFilter (ale)
+
+	    sys.exit (app.exec_())
+
+
+
+Before we enter the mainloop of the application, UserAle needs to register the application to be instrumented. 
+Simply instantiate UserAle and install it as an event filter in your application. 
+
+::
+
+	# Initiate UserAle
+	ale = Ale ()
+	# install globally
+	app.installEventFilter (ale)