Browse Source

doc review part 2

alexena 8 years ago
parent
commit
e41a0f4262
9 changed files with 194 additions and 188 deletions
  1. 7 3
      Docs/brain.md
  2. 5 3
      Docs/dev_env_install.md
  3. 13 7
      Docs/kalliope_cli.md
  4. 5 5
      Docs/neuron_list.md
  5. 12 14
      Docs/neurons.md
  6. 133 0
      Docs/rest_api.md
  7. 13 150
      Docs/signals.md
  8. 5 5
      Docs/stt.md
  9. 1 1
      Docs/trigger.md

+ 7 - 3
Docs/brain.md

@@ -44,8 +44,8 @@ At the top level we have a "name" tag. This is the **unique identifier** of the
 Then we have the neurons declaration. Neurons are modules that will be executed when the input action is triggered. You can define as many neurons as you want to the same input action (for example: say somethning, then do something etc...). This declaration contains a list (because it starts with a "-") of neurons
 ```
 neurons:
-    - neuron_name
-    - neuron_2
+    - neuron_1_name
+    - neuron_2_name
     - another_neuron
 ```
 
@@ -98,10 +98,14 @@ signals:
 ```
 When you will pronounce "say hello", it will trigger both synapses. 
 
+## Manage synapses
+
+Kalliope provides also a REST API to manage your synapses (get the list, get one, run one), refer to [rest api documentation](rest_api.md) for more details.
+
 
 ## Split the brain
 
-If you want a better visibly, or simply sort your actions with different file, you can split the main brain file into multiple one.
+If you want a better visibly, or simply sort your actions in different files, you can split the main brain file into multiple ones.
 
 To do that, use the import statement in the entry brain.yml file with the following syntax:
 

+ 5 - 3
Docs/dev_env_install.md

@@ -1,16 +1,18 @@
 # Dev environment installation
 
-This documentation aims at explaining the step by step manual deployment of Kalliope.
+This documentation aims at explaining step by step manual deployment of Kalliope.
 
 Tested env
 - Ubuntu 16.04
 
 
 
-## Prerequisite
+## Prerequisites
 
 ### Packages installation
-On Ubuntu distribution:
+To make Kalliope work, you will have to install a certain number of libraries
+
+On Ubuntu distribution :
 ```
 sudo apt-get install python-pip python-dev libsmpeg0 libttspico-utils libsmpeg0 flac dialog libffi-dev portaudio19-dev build-essential libssl-dev libffi-dev sox libatlas3-base
 ```

+ 13 - 7
Docs/kalliope_cli.md

@@ -17,7 +17,7 @@ python kalliope.py start
 ### start
 Start Kalliope main program
 
-Example usage
+Example of use
 ```
 python kalliope.py start
 ```
@@ -26,32 +26,38 @@ To kill Kalliope, you can press "Ctrl-C" on your keyboard.
 
 ### gui
 Launch the Kalliope shell Graphical User Interface. 
-The GUI allow you to test your [STT](stt.md) and [TTS](tts.md) that you have configured in [settings.yml](default_settings.md) file of Kalliope.
+The GUI allows you to test your [STT](stt.md) and [TTS](tts.md) that you have configured in [settings.yml](default_settings.md) file of Kalliope.
 
-Example usage
+Example of use
 ```
 python kalliope.py gui
 ```
 
 ## OPTIONS
 
+Commands can be completed by the following options:
+
 ### --run-synapse SYNAPSE_NAME
 
 Run a specific synapse from the brain file.
 
-Example usage
+Example of use
 ```
 python kalliope.py start --run-synapse "say hello"
 ```
 
 ### --brain-file BRAIN_FILE
 
-To use another brain file than the default one from the root of the project folder.
+Replace the default brain file from the root of the project folder by a custom one.
 > **Important note:** The path must be absolute. The absolute path contains the root directory and all other subdirectories in which a file or folder is contained. 
 
-Example usage
+Example of use
 ```
 python kalliope.py start --brain-file /home/me/my_other_brain.yml
+```
+
+You can combine the options together like, for example:
+```
 python kalliope.py start --run-synapse "say hello" --brain-file /home/me/my_other_brain.yml
 ```
 
@@ -59,7 +65,7 @@ python kalliope.py start --run-synapse "say hello" --brain-file /home/me/my_othe
 
 Show debug output in the console
 
-Example usage
+Example of use
 ```
 python kalliope.py start --debug
 ```

+ 5 - 5
Docs/neuron_list.md

@@ -1,18 +1,18 @@
 # List of available neuron
 
-A neuron is a module you can use in your synapses. See the [complete neuron documentation](neurons.md) for more information.
+A neuron is a module that will perform some actions attached to an order. You can use it in your synapses. See the [complete neuron documentation](neurons.md) for more information.
 
 | Name                                               | Description                                                                             | Used to sort      |
 |----------------------------------------------------|-----------------------------------------------------------------------------------------|-------------------|
 | [ansible_task](../neurons/ansible_task/)           | Run an ansible playbook                                                                 | ansible_task      |
 | [gmail_checker](../neurons/gmail_checker/)         | Get the number of unread email and their subjects from a gmail account                  | gmail_checker     |
-| [kill_switch](../neurons/kill_switch/)             | Stop Jarvis process                                                                     | kill_switch       |
+| [kill_switch](../neurons/kill_switch/)             | Stop Kalliope process                                                                   | kill_switch       |
 | [push_message](../neurons/push_message/)           | Send a push message to a remote device like Android/iOS/Windows Phone or Chrome browser | push_message      |
-| [say](../neurons/say/)                             | Make Jarvis talk by using TTS                                                           | say               |
+| [say](../neurons/say/)                             | Make Kalliope talk by using TTS                                                         | say               |
 | [script](../neurons/script/)                       | Run an executable script                                                                | script            |
 | [shell](../neurons/command/)                       | Run a shell command                                                                     | shell             |
-| [sleep](../neurons/sleep/)                         | Make Jarvis sleep for a while before continuing                                         | sleep             |
+| [sleep](../neurons/sleep/)                         | Make Kalliope sleep for a while before continuing                                       | sleep             |
 | [systemdate](../neurons/systemdate/)               | Give the local system date and time                                                     | systemdate        |
 | [tasker_autoremote](../neurons/tasker_autoremote/) | Send a message to Android tasker app                                                    | tasker_autoremote |
-| [twitter](../neurons/twitter/)                     | Send a Twit from kalliope                                                               | twitter           |
+| [twitter](../neurons/twitter/)                     | Send a Twit from Kalliope                                                               | twitter           |
 

+ 12 - 14
Docs/neurons.md

@@ -1,19 +1,19 @@
 # Neurons
 
-A neuron is a plugin that you can use in a synapse to perform action. 
-Neurons are executed one by one when the input action is triggered.
+A neuron is a plugin that performs an action attached to some action. You can use it in to create a synapse.  
+You can add as many neurons as you want to a synapse. The neurons are executed one by one when the input action is triggered.
 
 ## Usage
 Neurons are declared in the `neurons` section of a synapse in your brain file.
-The `neurons` section is a list (because it starts with a "-") which contains neuron module name
+The `neurons` section is a list (because it starts with a "-") which contains neuron modules names
 ```
 neurons:
-    - neuron_name
-    - neuron_2
+    - neuron_1_name
+    - neuron_2_name
     - another_neuron
 ```
 
-Some neurons need parameters that can be passed as argument following the syntax bellow:
+Some neurons need parameters that can be passed as arguments following the syntax bellow:
 ```
 neurons:
     - neuron_name:
@@ -22,7 +22,7 @@ neurons:
 ```
 > **note:** parameters are indented with two spaces bellow the neuron's name following the YAML syntax.
 
-To know which parameter are required, check of documentation of the neuron.
+To know the list of required parameters, check of documentation of the neuron.
 Full list of [available neuron here](neuron_list.md)
 
 ## Overridable parameters
@@ -32,18 +32,16 @@ set in [settings.yml](settings.yml) file.
 
 ### Cache
 
-You can choose to override the default cache configuration. By default Kalliope use a cache to save a generated audio from a TTS engine.
-This cache is usefull when you know that the text to speech will not change like in the following example
+You can override the default cache configuration. By default Kalliope uses a cache to save a generated audio from a TTS engine.
+This cache is usefull to not to regenerate often used sentences that are not suppose to be changed very often. For exemple, the following sentence will not change in time, so it's more optimized to generate it once and to keep it in cash:
 ```
 - say:
     message:
       - "Hello, sir"
 ```
 
-In some case, and more specially when the neuron is based on a template, the generated audio will change at each new call of the neuron and so the usage 
-of a cache is not necessary. 
-The best example is when you use the `systemdate` neuron. As the time change every minute, the generated audio will change too.
-Saving a cache of the generated audio is useless in this case. It where the usage of a cache override become usefull.
+In some cases, especially when the neuron is based on a template, the generated audio will change at each new call of the neuron and so the usage 
+of a cache is not necessary. The best example of the case like this is the `systemdate` neuron. As the time changes every minute, the generated audio will change too and so, saving the generated audio in the cache is useless. In this case, you can override the cache usage for this neuron:
 ```
 - systemdate:
     say_template:
@@ -53,7 +51,7 @@ Saving a cache of the generated audio is useless in this case. It where the usag
 
 ### tts
 
-You can override the default tts in each neurons. Just add the tts parameter to the neuron like in the example bellow
+You can override the default tts for each neurons. Just add the "tts" parameter to the neuron like in the example bellow
 ```
 neurons:
   - say:

+ 133 - 0
Docs/rest_api.md

@@ -0,0 +1,133 @@
+# Rest API
+
+Kalliope provides the REST API to manage the synapses. For configuring the API refer to the [settings documentation](settings.md).
+
+## Synapse API
+
+| Method | URL                      | Action               |
+|--------|--------------------------|----------------------|
+| GET    | /synapses                | List synapses        |
+| GET    | /synapses/<synapse_name> | Show synapse details |
+| POST   | /synapses/<synapse_name> | Run a synapse        |
+
+## Curl examples
+
+>**Note:** --user is only needed if `password_protected` is True
+
+### Get all synapse
+
+Normal response codes: 200
+Error response codes: unauthorized(401), itemNotFound(404)
+Curl command:
+```
+curl -i --user admin:secret -X GET  http://localhost:5000/synapses/
+```
+
+Output example:
+```
+{
+  "synapses": [
+    [
+      {
+        "name": "stop-kalliope",
+        "neurons": [
+          {
+            "say": {
+              "message": "Good bye"
+            }
+          },
+          "kill_switch"
+        ],
+        "signals": [
+          {
+            "order": "close"
+          }
+        ]
+      }
+    ],
+    [
+      {
+        "name": "say-hello",
+        "neurons": [
+          {
+            "say": {
+              "message": [
+                "Bonjour monsieur"
+              ]
+            }
+          }
+        ],
+        "signals": [
+          {
+            "order": "bonjour"
+          }
+        ]
+      }
+    ]
+  ]
+}
+```
+
+### Get one synapse's detail by its name. 
+
+Normal response codes: 200
+Error response codes: unauthorized(401), itemNotFound(404)
+Curl command:
+```
+curl -i --user admin:secret -X GET  http://localhost:5000/synapses/say-hello
+```
+
+Output example:
+```
+{
+  "synapses": {
+    "name": "say-hello",
+    "neurons": [
+      {
+        "say": {
+          "message": [
+            "Bonjour monsieur"
+          ]
+        }
+      }
+    ],
+    "signals": [
+      {
+        "order": "bonjour"
+      }
+    ]
+  }
+}
+```
+
+### Run a synapse by its name. 
+
+Normal response codes: 201
+Error response codes: unauthorized(401), itemNotFound(404)
+Curl command:
+```
+curl -i --user admin:secret -X POST  http://localhost:5000/synapses/say-hello
+```
+
+Output example:
+```
+{
+  "synapses": {
+    "name": "say-hello",
+    "neurons": [
+      {
+        "say": {
+          "message": [
+            "Bonjour monsieur"
+          ]
+        }
+      }
+    ],
+    "signals": [
+      {
+        "order": "bonjour"
+      }
+    ]
+  }
+}
+```

+ 13 - 150
Docs/signals.md

@@ -1,11 +1,11 @@
 # Signals
 
-A signal is an input event triggered by a synapse. When a signal is caught, Kalliope run attached neurons of the synapse.
+A signal is an input event triggered by a synapse. When a signal is caught, Kalliope runs attached neurons of the synapse. The signal can be of two types: order and event.
 
 The syntax is the following
 ```
 signals:
-    - signal_name: parameter
+    - signal_type: parameter
 ```
 
 ## Order
@@ -24,15 +24,13 @@ signals:
     - order: "please do this action"
 ```
 
-> **Important note:** SST engines can misunderstand what you say, or return a text from the speech you said with some spelling mistake.
-For example, if you say "Kalliope please do this", the SST engine can return "caliope please do this". The recommended way is to test your STT engine by using the
-[Kalliope GUI](kalliope_cli.md) and see what is the returned text for the given order.
+> **Important note:** SST engines can misunderstand what you say, or translate your sentence into text containing some spelling mistakes.
+For example, if you say "Kalliope please do this", the SST engine can return "caliope please do this". So, to be sure that your speaking order will be correctly caught and executed, we recommend you to test your STT engine by using the [Kalliope GUI](kalliope_cli.md) and check the returned text for the given order.
 
-> **Important note:** Kalliope will try to match the order in each synapse of his brain, if an order of one synapse is included in another order of another synapse, then both synapse task will 
-be started by Kalliope.
+> **Important note:** Kalliope will try to match the order in each synapse of its brain. So, if an order of one synapse is included in another order of another synapse, then both synapses tasks will be started by Kalliope.
 
-> For example, if you have "test my umbrella" in a synapse A and "test" in a synapse B. When you'll say "test my umbrella", both synapse A and B
-will be started by Kalliope. So keep in mind that is a best practice to use different sentences with more than one word.
+> For example, you have "test my umbrella" in a synapse A and "test" in a synapse B. When you'll say "test my umbrella", both synapse A and B
+will be started by Kalliope. So keep in mind that the best practice is to use really different sentences with more than one word for your order.
 
 ## Event
 
@@ -40,16 +38,15 @@ An event is a way to schedule the launching of a synapse periodically at fixed t
 
 The event system is based on [Linux crontab](https://en.wikipedia.org/wiki/Cron). A crontab is file that specifies shell commands to run periodically
  on a given schedule.
-When you declare an event in the brain, Kalliope will load the crontab file for you for scheduling the launching 
-of the  target synapse.
+When you declare an event in the signal, Kalliope will load the crontab file to schedule the launching of the target synapse.
 
 The syntax of an event declaration in a synapse is the following
 ```
 signals:
-      - event: "<contab period>"
+    - event: "<contab period>"
 ```
 
-Where a crontab period use the syntax bellow
+Where a crontab period follows the syntax bellow:
 ```
  ┌───────────── min (0 - 59)
  │ ┌────────────── hour (0 - 23)
@@ -62,12 +59,12 @@ Where a crontab period use the syntax bellow
  * * * * *  
 ```
 
-For example, if we want Kalliope to run the synapse every day a 8 PM. The event would be
+For example, if we want Kalliope to run the synapse every day a 8 PM, the event will be declared like this:
 ```
 - event: "0 20 * * *"
 ```
 
-Let make a complete example. We want Kalliope to wake us up each morning of working day (Monday to friday) at 7 AM and:
+Let's make a complete example. We want Kalliope to wake us up each morning of working day (Monday to friday) at 7 AM and:
 - Wish us good morning
 - Give us the time
 - Play our favourite web radio
@@ -92,144 +89,10 @@ After setting up an event, you must restart Kalliope
 python kalliope.py start
 ```
 
-If the syntax is ok, Kalliope will show you each synapse that he has loaded in the crontab
+If the syntax is ok, Kalliope will show you each synapse that it has loaded in the crontab
 ```
 Synapse "wake up" added to the crontab
 Event loaded in crontab
 ```
 
 That's it, the synapse is now scheduled and will be started automatically.
-
-## Rest API
-
-Each synapse can be started from the REST API. For configuring the API see the [settings documentation](settings.md).
-
-### Synapse API
-
-| Method | URL                      | Action               |
-|--------|--------------------------|----------------------|
-| GET    | /synapses                | List synapses        |
-| GET    | /synapses/<synapse_name> | Show synapse details |
-| POST   | /synapses/<synapse_name> | Run a synapse        |
-
-### Curl examples
-
->**Note:** --user is only needed if `password_protected` is True
-
-#### Get all synapse
-
-Normal response codes: 200
-Error response codes: unauthorized(401), itemNotFound(404)
-Curl command:
-```
-curl -i --user admin:secret -X GET  http://localhost:5000/synapses/
-```
-
-Output example:
-```
-{
-  "synapses": [
-    [
-      {
-        "name": "stop-kalliope",
-        "neurons": [
-          {
-            "say": {
-              "message": "Good bye"
-            }
-          },
-          "kill_switch"
-        ],
-        "signals": [
-          {
-            "order": "close"
-          }
-        ]
-      }
-    ],
-    [
-      {
-        "name": "say-hello",
-        "neurons": [
-          {
-            "say": {
-              "message": [
-                "Bonjour monsieur"
-              ]
-            }
-          }
-        ],
-        "signals": [
-          {
-            "order": "bonjour"
-          }
-        ]
-      }
-    ]
-  ]
-}
-```
-
-#### Get synapse's detail. 
-
-Normal response codes: 200
-Error response codes: unauthorized(401), itemNotFound(404)
-Curl command:
-```
-curl -i --user admin:secret -X GET  http://localhost:5000/synapses/say-hello
-```
-
-Output example:
-```
-{
-  "synapses": {
-    "name": "say-hello",
-    "neurons": [
-      {
-        "say": {
-          "message": [
-            "Bonjour monsieur"
-          ]
-        }
-      }
-    ],
-    "signals": [
-      {
-        "order": "bonjour"
-      }
-    ]
-  }
-}
-```
-
-#### Run a synapse by its name. 
-
-Normal response codes: 201
-Error response codes: unauthorized(401), itemNotFound(404)
-Curl command:
-```
-curl -i --user admin:secret -X POST  http://localhost:5000/synapses/say-hello
-```
-
-Output example:
-```
-{
-  "synapses": {
-    "name": "say-hello",
-    "neurons": [
-      {
-        "say": {
-          "message": [
-            "Bonjour monsieur"
-          ]
-        }
-      }
-    ],
-    "signals": [
-      {
-        "order": "bonjour"
-      }
-    ]
-  }
-}
-```

+ 5 - 5
Docs/stt.md

@@ -1,11 +1,11 @@
 # Speech To Text (STT)
 
-This chapter describes how STT are working.
+This chapter describes how STT engine works.
 
-The STT are programs or API that converts the voice to text.
-Each of them have a specific configuration and support multiple voice and/or languages.
+The STT is a programs or API that converts the speech into text.
+Each STT has a specific configuration and supports multiple voices and/or languages.
 
-The configuration for each STT must apply in the [settings.yml](settings.md) file.
+The configuration of each STT you use must appear in the [settings.yml](settings.md) file.
 
 The syntax used is YAML.
 
@@ -16,7 +16,7 @@ The setting.yml defines the STT you want to use by default
 default_speech_to_text: "type default STT here"
 ```
 
-Then, still in the settings.yml file, each STT must set up its configuration following 'speech_to_text' tag :
+Then, still in the settings.yml file, each STT must set up its configuration following the 'speech_to_text' tag :
 ```
 speech_to_text:
    - STT1:

+ 1 - 1
Docs/trigger.md

@@ -1,6 +1,6 @@
 
 
-With Kalliope project, you can set the Hotword you want. You can create your magic word by connecting to [Snowboy](https://snowboy.kitt.ai/) 
+With Kalliope project, you can set whatever Hotword you want to wake it up. You can create your magic word by connecting to [Snowboy](https://snowboy.kitt.ai/) 
 and then download the trained model file.
 
 Once downloaded, place the file in **trigger/snowboy/resources**.