Skip to content

Commit b2fb444

Browse files
rcbyronrcbyron
committed
Updated docs
1 parent 0b6acac commit b2fb444

File tree

7 files changed

+163
-117
lines changed

7 files changed

+163
-117
lines changed

‎README.rst‎

Lines changed: 40 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Echo can do - and more.
1616
Written in Python 3
1717

1818
| **Website:** http://heyathena.com
19-
| **Documentation:** http://pythonhosted.org/HeyAthena/
19+
| **Documentation:** http://heyathena.com/docs/
2020
| **GitHub:** https://github.com/hey-athena/hey-athena-client
2121
2222
Usage Examples:
@@ -64,72 +64,9 @@ Core Dependencies
6464
- PyYAML
6565
- Selenium
6666

67-
Ubuntu Installation
68-
-------------------
69-
- ``sudo apt-get update -y``
70-
- ``sudo apt-get install -y python3 python3-dev python3-pip build-essential swig git portaudio19-dev python3-pyaudio flac``
71-
- ``sudo pip3 install pocketsphinx HeyAthena``
72-
73-
- Install AVBin 10:
74-
75-
- http://avbin.github.io/AVbin/Download.html
76-
- ``chmod +x ./install-avbin-linux-XXX-XX-v10``
77-
- ``sudo ./install-avbin-linux-XXX-XX-v10``
78-
79-
- ``sudo python3``
80-
- ``>>> from athena import __main__``
81-
82-
- If all goes well, create a user, say "Athena", and ask her a question!
83-
- Otherwise post an issue describing the error to the GitHub repository linked above
84-
- You can add modules/edit the client in Python's site-packages/athena
85-
folder
86-
- Try writing your own module using the directions below!
87-
88-
Normal Installation (Mac/Windows)
89-
---------------------------------
90-
91-
- Install SWIG (only required to install pocketsphinx and can be
92-
removed afterward)
93-
94-
- Mac: using Homebrew package manager, type ``brew install swig``
95-
- Windows: http://www.swig.org/download.html (download swigwin-3.X.X
96-
and place swig.exe in your environment PATH)
97-
98-
- Install PyAudio:
99-
100-
- Mac: ``brew install portaudio`` ``pip install pyaudio```
101-
- Windows: ``python -m pip install pyaudio``
102-
103-
- Install AVBin:
104-
105-
- http://avbin.github.io/AVbin/Download.html
106-
- *Windows Only*: verify that the avbin.dll or avbin64.dll was placed in SysWOW64 not System32
107-
108-
- ``pip3 install HeyAthena``
109-
- Now open up Python 3 and run ``>>> from athena import __main__``
110-
111-
- If all goes well, create a user, say "Athena", and ask her a question!
112-
- Otherwise post an issue describing the error to the GitHub repository linked above
113-
- You can add modules/edit the client in Python's site-packages/athena
114-
folder
115-
- Try writing your own module using the directions below!
116-
117-
Developer Installation
118-
----------------------
119-
120-
- Install SWIG, PyAudio, and AVBin using the directions above
121-
- ``pip3 install pocketsphinx pyaudio SpeechRecognition pyglet gTTS pyyaml wolframalpha selenium``
122-
- Clone or download the ``hey-athena-client`` repository
123-
- Add ``C:\path\to\hey-athena-client`` to your ``PYTHONPATH`` system or
124-
user environment variable
125-
126-
- Eclipse (PyDev) has an option for this while importing the project
127-
from Git
128-
129-
- ``cd hey-athena-client-master\client``
130-
- If all goes well, run ``__main__.py``, create a user, say "Athena",
131-
and ask her a question!
132-
- Now try write your own module using the directions below!
67+
Installation
68+
------------
69+
For installation notes, please use: http://heyathena.com/docs/intro/install.html
13370

13471
Active Modules
13572
--------------
@@ -143,47 +80,42 @@ priority is taken into account first, then task priority.
14380

14481
.. code:: python
14582
146-
"""
147-
Finds and returns the latest bitcoin price
148-
149-
Usage Examples:
150-
- "What is the price of bitcoin?"
151-
- "How much is a bitcoin worth?"
152-
"""
153-
154-
from athena.classes.module import Module
155-
from athena.classes.task import ActiveTask
156-
from athena.api_library import bitcoin_api
157-
158-
# Only a unique name parameter is required
159-
# See other parameters in athena/classes/module.py
160-
MOD_PARAMS = {
161-
'name': 'bitcoin',
162-
'priority': 2,
163-
}
164-
165-
# A task matches text patterns and executes Python code accordingly
166-
class GetValueTask(ActiveTask):
167-
168-
def __init__(self):
169-
# Give regex patterns to match text input
170-
super().__init__(patterns=[r'.*\b(bitcoin)\b.*'])
171-
172-
def match(self, text):
173-
# See if the text matches any pattern
174-
return self.match_any(text)
175-
176-
def action(self, text):
177-
# If any pattern matched, speak the bitcoin price
178-
val = str(bitcoin_api.get_data('last'))
179-
self.speak(val)
180-
181-
# This is a bare-minimum module
182-
class Bitcoin(Module):
183-
184-
def __init__(self):
185-
tasks = [GetValueTask()]
186-
super().__init__(MOD_PARAMS, tasks)
83+
"""
84+
File Name: hello_world.py
85+
Finds and returns the latest bitcoin price
86+
87+
Usage Examples:
88+
- "What is the price of bitcoin?"
89+
- "How much is a bitcoin worth?"
90+
"""
91+
92+
from athena.classes.module import Module
93+
from athena.classes.task import ActiveTask
94+
from athena.api_library import bitcoin_api
95+
96+
class GetValueTask(ActiveTask):
97+
98+
def __init__(self):
99+
# Matches any statement with the word "bitcoin"
100+
super().__init__(words=['bitcoin'])
101+
102+
# This default match method can be overridden
103+
# def match(self, text):
104+
# # "text" is the STT translated input string
105+
# # Return True if the text matches any word or pattern
106+
# return self.match_any(text)
107+
108+
def action(self, text):
109+
# If 'bitcoin' was found in text, speak the bitcoin price
110+
bitcoin_price = str(bitcoin_api.get_data('last'))
111+
self.speak(bitcoin_price)
112+
113+
# This is a bare-minimum module
114+
class Bitcoin(Module):
115+
116+
def __init__(self):
117+
tasks = [GetValueTask()]
118+
super().__init__('bitcoin', tasks, priority=2)
187119
188120
Module Ideas
189121
~~~~~~~~~~~~

‎docs/api/athena.classes.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,14 @@ athena.classes.api module
1717
:undoc-members:
1818
:show-inheritance:
1919

20+
athena.classes.input_field module
21+
---------------------------------
22+
23+
.. automodule:: athena.classes.input_field
24+
:members:
25+
:undoc-members:
26+
:show-inheritance:
27+
2028
athena.classes.module module
2129
----------------------------
2230

‎docs/api/athena.modules.active.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,14 @@ athena.modules.active package
99
Submodules
1010
----------
1111

12+
athena.modules.active.athena_control module
13+
-------------------------------------------
14+
15+
.. automodule:: athena.modules.active.athena_control
16+
:members:
17+
:undoc-members:
18+
:show-inheritance:
19+
1220
athena.modules.active.bitcoin module
1321
------------------------------------
1422

‎docs/intro/install.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
Installation Notes
22
==================
3-
Use the "Manual (GitHub) Installation" to debug installation issues.
3+
For troubleshooting, use the "Developer (GitHub) Installation". Post any issues (with detailed error messages) to the GitHub repository.
44

55
Ubuntu/Raspberry Pi/Linux
66
-------------------------
@@ -45,8 +45,8 @@ Mac OS X
4545
- ``pip3 install HeyAthena``
4646
- Now open up Python 3 and run ``>>> from athena import __main__``
4747

48-
Manual (GitHub) Installation
49-
----------------------------
48+
Developer (GitHub) Installation
49+
-------------------------------
5050
- Install SWIG, PyAudio, and AVBin using the directions above (depending on your operating system)
5151
- ``pip3 install pocketsphinx pyaudio SpeechRecognition pyglet gTTS pyyaml wolframalpha selenium``
5252
- Clone or download the ``hey-athena-client`` repository
@@ -64,6 +64,6 @@ Okay I think I've installed everything. Now what?
6464

6565
- If all goes well, create a user, say "Athena", and ask her a question!
6666
- Otherwise post an issue describing the error to the GitHub repository linked above
67+
- Continue to personalize Athena by writing your own module
6768
- You can add modules/edit the client in Python's site-packages/athena
68-
folder
69-
- Try writing your own module using the directions below!
69+
folder

‎docs/intro/overview.rst‎

Lines changed: 56 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,59 @@
11
Overview
22
========
3+
"Hey Athena" is a 100% open-source, cross-platform, modular voice assistant framework written in Python 3. Our goal is to help you control things with your voice. This is accomplished by writing simple (module).py files.
34

4-
Here is an overview of Hey Athena.
5+
| **Website:** http://heyathena.com
6+
| **Documentation:** http://heyathena.com/docs/
7+
| **GitHub:** https://github.com/hey-athena/hey-athena-client
8+
|
9+
10+
The Big Picture
11+
---------------
12+
|Graphic Overview|
13+
14+
Active Modules
15+
--------------
16+
An Active Module is simply a collection of "Active Tasks".
17+
Users can create "Active Modules" which allow Athena to respond to different commands.
18+
The "Weather" module, for example, handles questions like "Is it cold outside?", "What is the forecast for tonight?"
19+
20+
Active Tasks
21+
------------
22+
An Active Task looks for matches in user input to decide whether or not to execute an action.
23+
If the task's "match" method returns true, then the task action is added to the module's task queue.
24+
25+
Input Matching Order
26+
--------------------
27+
Both Active Modules and Active Tasks have a "priority" attribute and a "greedy" attribute.
28+
29+
For priority, higher number means the module or task is matched/executed first (e.g. - priority 5 is executed before priority 1)
30+
31+
If a module or task is greedy, then no other lower priority modules or tasks can match/execute afterward.
32+
33+
**Here is a basic idea of the input matching scheme:**
34+
35+
.. code:: python
36+
37+
sort modules based on priority
38+
for each mod in modules:
39+
mod.task_queue = []
40+
for each task in sorted(mod.tasks):
41+
if task.match(text):
42+
mod.task_queue.append(task)
43+
if task.greedy:
44+
break
45+
46+
if mod matched one or more tasks:
47+
self.matched_mods.append(mod)
48+
49+
Roadmap
50+
-------
51+
Hey Athena is just getting started. We plan to build an open-source community built around our voice assistance framework. Here are some features you can expect to see in the future:
52+
53+
- **Passive Modules:** useful for voice/text notifications (e.g. - Unread email, Twitter notifications)
54+
- **Web App Demo:** we are in the process of making a simple web app demo for Hey Athena
55+
- **Bigger Community:** we are working on building a bigger open-source community
56+
- **HTTP REST API Service:** users will be able to send HTTP requests and receive a voice/text JSON response (e.g. - ``HTTP GET http://heyathena.com/api/{api_key}/q=list%20bitcoin%20price``)
57+
58+
.. |Graphic Overview| image:: http://heyathena.com/images/graphic.png
59+
:target: http://heyathena.com/images/graphic.png

‎docs/intro/tutorial.rst‎

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,47 @@
11
Hello World
22
===========
33

4-
Here is a basic tutorial.
4+
You can add modules/edit the client in the ".../athena/modules/active" folder.
5+
6+
For normal installations, the "athena" folder is stored in Python's "site-packages" folder
7+
8+
Here is an example module (add to ".../athena/modules/active")
9+
10+
.. code:: python
11+
12+
"""
13+
File Name: hello_world.py
14+
Finds and returns the latest bitcoin price
15+
16+
Usage Examples:
17+
- "What is the price of bitcoin?"
18+
- "How much is a bitcoin worth?"
19+
"""
20+
21+
from athena.classes.module import Module
22+
from athena.classes.task import ActiveTask
23+
from athena.api_library import bitcoin_api
24+
25+
class GetValueTask(ActiveTask):
26+
27+
def __init__(self):
28+
# Matches any statement with the word "bitcoin"
29+
super().__init__(words=['bitcoin'])
30+
31+
# This default match method can be overridden
32+
# def match(self, text):
33+
# # "text" is the STT translated input string
34+
# # Return True if the text matches any word or pattern
35+
# return self.match_any(text)
36+
37+
def action(self, text):
38+
# If 'bitcoin' was found in text, speak the bitcoin price
39+
bitcoin_price = str(bitcoin_api.get_data('last'))
40+
self.speak(bitcoin_price)
41+
42+
# This is a bare-minimum module
43+
class Bitcoin(Module):
44+
45+
def __init__(self):
46+
tasks = [GetValueTask()]
47+
super().__init__('bitcoin', tasks, priority=2)

‎setup.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,13 @@
2525
# Versions should comply with PEP440. For a discussion on single-sourcing
2626
# the version across setup.py and the project code, see
2727
# https://packaging.python.org/en/latest/single_source_version.html
28-
version='1.1.1',
28+
version='1.2.1',
2929

3030
description='Your personal voice assistant',
3131
long_description=long_description,
3232

3333
# The project's main homepage.
34-
url='http://heyathena.com',
34+
url='http://heyathena.com/docs/',
3535

3636
# Author details
3737
author='Hey Athena',

0 commit comments

Comments
 (0)