Updated documentation. Included brief instrumentation guide.
diff --git a/.travis.yaml b/.travis.yaml
index 76722fe..2d06779 100644
--- a/.travis.yaml
+++ b/.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
diff --git a/AUTHORS.txt b/AUTHORS
similarity index 90%
rename from AUTHORS.txt
rename to AUTHORS
index 0386801..4d69944 100644
--- a/AUTHORS.txt
+++ b/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>
diff --git a/CHANGELOG.txt b/CHANGELOG
similarity index 100%
rename from CHANGELOG.txt
rename to CHANGELOG
diff --git a/LICENSE.txt b/LICENSE
similarity index 100%
rename from LICENSE.txt
rename to LICENSE
diff --git a/MANIFEST.in b/MANIFEST.in
index 6334d32..05ae03a 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,5 +1,6 @@
include MANIFEST.in
include setup.py
-include README.txt
-include CHANGELOG.txt
-include LICENSE.txt
\ No newline at end of file
+include README
+include AUTHORS
+include CHANGELOG
+include LICENSE
\ No newline at end of file
diff --git a/README b/README
new file mode 100644
index 0000000..50e45fd
--- /dev/null
+++ b/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.
diff --git a/README.txt b/README.txt
deleted file mode 100644
index a39bcfd..0000000
--- a/README.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-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.
-
-License
-=======
-
-Copyright 2016 The Charles Stark Draper Laboratory, Inc.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
\ No newline at end of file
diff --git a/docs/source/authors.rst b/docs/source/authors.rst
index 201880a..e8106a9 100644
--- a/docs/source/authors.rst
+++ b/docs/source/authors.rst
@@ -1,4 +1,4 @@
Authors
-------
-.. include:: ../../AUTHORS.txt
\ No newline at end of file
+.. include:: ../../AUTHORS
\ No newline at end of file
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
index 609466b..0143bc5 100644
--- a/docs/source/changelog.rst
+++ b/docs/source/changelog.rst
@@ -3,4 +3,4 @@
Here you can see the full list of changes between each UserAle.pyqt5 release.
-.. include:: ../../CHANGELOG.txt
+.. include:: ../../CHANGELOG
diff --git a/docs/source/conf.py b/docs/source/conf.py
index b38e0ff..76ee93d 100644
--- a/docs/source/conf.py
+++ b/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
diff --git a/docs/source/contents.rst.inc b/docs/source/contents.rst.inc
index 6fad61b..59fa596 100644
--- a/docs/source/contents.rst.inc
+++ b/docs/source/contents.rst.inc
@@ -10,7 +10,7 @@
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
diff --git a/docs/source/index.rst b/docs/source/index.rst
index c81cbe2..ec1ac6d 100644
--- a/docs/source/index.rst
+++ b/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`
-
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 3fea99d..e3ca3fb 100644
--- a/docs/source/installation.rst
+++ b/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
\ No newline at end of file
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
index 650d040..ba1b7d2 100644
--- a/docs/source/quickstart.rst
+++ b/docs/source/quickstart.rst
@@ -1,4 +1,58 @@
.. _quickstart:
Quickstart Guide
-================
\ No newline at end of file
+================
+
+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)
