Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
Browse files
Updated documentation. Included brief instrumentation guide.
  • Loading branch information
mooshu1x2 committed Jul 15, 2016
1 parent 2ef4666 commit 9fe498b0c922285ce247a8800537ecac3b6cbfe0
Showing 14 changed files with 191 additions and 49 deletions.
@@ -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
@@ -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>

File renamed without changes.
File renamed without changes.
@@ -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
8 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.

This file was deleted.

@@ -1,4 +1,4 @@
Authors
-------

.. include:: ../../AUTHORS.txt
.. include:: ../../AUTHORS
@@ -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
@@ -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
@@ -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
@@ -1,14 +1,5 @@
:orphan:

Apache UserAle's documentation!
===============================
.. include:: ../../README

.. include:: contents.rst.inc

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

@@ -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
@@ -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)

0 comments on commit 9fe498b

Please sign in to comment.