浏览代码

doc update

nico 8 年之前
父节点
当前提交
c560a7b78e
共有 5 个文件被更改,包括 90 次插入15 次删除
  1. 4 1
      Docs/brain.md
  2. 44 4
      Docs/contributing.md
  3. 8 9
      Docs/kalliope_cli.md
  4. 2 1
      Docs/neurons.md
  5. 32 0
      Docs/signals.md

+ 4 - 1
Docs/brain.md

@@ -9,7 +9,7 @@ An input action, called a "[signal](signals.md)" can be:
 - **an event:** A date or a frequency (E.G: repeat each morning at 8:30)
 
 An output action is
-- **a list of neurons:** A [neuron](neurons.md) is a module or plugin that will perform some actions like simply talking, run a script, run a command or a complex Ansible playbook.
+- **a list of neurons:** A [neuron](neurons.md) is a module or plugin that will perform some actions like simply talking, run a script, run a command or call a web service.
 
 Brain is expressed in YAML format (see YAML Syntax) and has a minimum of syntax, which intentionally tries to not be a programming language or script, 
 but rather a model of a configuration or a process.
@@ -134,4 +134,7 @@ You can provide a default synapse in case none of them are matching when an orde
 ## Next: Start Kalliope
 Now you take a look into the [CLI documentation](kalliope_cli.md) to learn how to start kalliope.
 
+## Notes
+- What is a [neuron](neurons.md)
+- What is a [signal](signals.md)
 

+ 44 - 4
Docs/contributing.md

@@ -58,10 +58,10 @@ The constructor has a __**kwargs argument__ which is corresponding to the Dict o
     ```
 
 1. You must run unit tests with success before sending a pull request. Add new tests that cover the code you want to publish.
-```
-cd /path/to/kalliope
-python -m unittest discover
-```
+    ```
+    cd /path/to/kalliope
+    python -m unittest discover
+    ```
 
 1. (*optionnal-> good practice*) The Neuron can implement a __private method _is_parameters_ok(self)__ which checks if entries are ok. *return: true if parameters are ok, raise an exception otherwise*
 1. (*optionnal-> good practice*) The Neuron can __import and raise exceptions__ coming from NeuronModule:
@@ -71,6 +71,46 @@ python -m unittest discover
 1. The Neuron can use a __self.say(message) method__ to speak out some return values using the *say_template* attribute in the brain file.
 the message variable must be a Dict of variable:values where variables can be defined as output.
 
+1. Example of neuron structure
+    ```
+    myneuron/
+    ├── __init__.py
+    ├── myneuron.py
+    ├── README.md
+    └── tests
+        ├── __init__.py
+        └── test_myneuron.py
+    ```
+
+1. Example of neuron code
+    ```
+    class Myneuron(NeuronModule):
+    def __init__(self, **kwargs):
+        super(Myneuron, self).__init__(**kwargs)
+        # ge args from the neuron configuration
+        self.arg1 = kwargs.get('arg1', None)
+        self.arg2 = kwargs.get('arg2', None)
+
+        # check if parameters have been provided
+        if self._is_parameters_ok():
+            # -------------------
+            # do amazing code
+            # -------------------            
+
+    def _is_parameters_ok(self):
+        """
+        Check if received parameters are ok to perform operations in the neuron
+        :return: true if parameters are ok, raise an exception otherwise
+
+        .. raises:: MissingParameterException
+        """
+        if self.arg1 is None:
+            raise MissingParameterException("You must specify a arg1")
+        if not isinstance(self.arg2, int):
+            raise MissingParameterException("arg2 must be an integer")
+        return True
+    ```
+
 ##### Constraints
 
 1. The Neuron must (as much as possible) ensure the i18n. This means that they should __not manage a specific languages__ inside its own logic.

+ 8 - 9
Docs/kalliope_cli.md

@@ -3,13 +3,12 @@
 ## SYNOPSIS
 This is the syntax used to run Kalliope from command line
 ```
-cd /path/to/kalliope
-python kalliope.py command --option <argument>
+kalliope command --option <argument>
 ```
 
 For example, to start Kalliope we simply use
 ```
-python kalliope.py start
+kalliope start
 ```
 
 ## ARGUMENTS
@@ -19,7 +18,7 @@ Start Kalliope main program
 
 Example of use
 ```
-python kalliope.py start
+kalliope start
 ```
 
 To kill Kalliope, you can press "Ctrl-C" on your keyboard.
@@ -30,7 +29,7 @@ The GUI allows you to test your [STT](stt.md) and [TTS](tts.md) that you have co
 
 Example of use
 ```
-python kalliope.py gui
+kalliope gui
 ```
 
 ## OPTIONS
@@ -43,7 +42,7 @@ Run a specific synapse from the brain file.
 
 Example of use
 ```
-python kalliope.py start --run-synapse "say hello"
+kalliope start --run-synapse "say-hello"
 ```
 
 ### --brain-file BRAIN_FILE
@@ -53,12 +52,12 @@ Replace the default brain file from the root of the project folder by a custom o
 
 Example of use
 ```
-python kalliope.py start --brain-file /home/me/my_other_brain.yml
+kalliope 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
+kalliope start --run-synapse "say-hello" --brain-file /home/me/my_other_brain.yml
 ```
 
 ### --debug
@@ -67,5 +66,5 @@ Show debug output in the console
 
 Example of use
 ```
-python kalliope.py start --debug
+kalliope start --debug
 ```

+ 2 - 1
Docs/neurons.md

@@ -55,6 +55,7 @@ From the captured order:
 Here, the spoken value captured by the TTS engine will be passed as an argument to the neuron in the variable named `parameter3`.
 
 Example, with the synapse declaration above, if you say "this is an order with the parameter Amy Winehouse". The neuron will receive a parameter named `parameter3` with "Amy Winehouse" as a value of this parameter.
+We recommend the reading of the [signals documentation](signals.md) for a complete understanding of how arguments in a neuron work.
 
 
 ## Output values
@@ -110,7 +111,7 @@ As this is multi-lines, we can put the content in a file and use a `file_templat
 ## Overridable parameters
 
 For each neuron, you can override some parameters to use a specific configuration of TTS instead of the default one 
-set in [settings.yml](settings.yml) file.
+set in [settings.yml](settings.md) file.
 
 ### Cache
 

+ 32 - 0
Docs/signals.md

@@ -10,6 +10,7 @@ signals:
 
 ## Order
 
+### Simple order
 An **order** signal is a word, or a sentence caught by the microphone and processed by the STT engine.
 
 Syntax:
@@ -32,6 +33,37 @@ For example, if you say "Kalliope please do this", the SST engine can return "ca
 > 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.
 
+### Order with arguments
+You can add one or more arguments to an order by adding bracket to the sentence.
+
+Syntax:
+```
+signals:
+    - order: "<sentence> {{ arg_name }}"
+    - order: "<sentence> {{ arg_name }} <sentence>"
+    - order: "<sentence> {{ arg_name }} <sentence> {{ arg_name }}"
+```
+
+Example:
+```
+signals:
+    - order: "I want to listen {{ artist_name }}"
+    - order: "start the {{ episode_number }} episode"
+    - order: "give me the weather at {{ location }} for {{ date }}"
+```
+
+Here, an example order would be speaking out loud the order: "I want to listen Amy Winehouse"
+In this example, both word "Amy" and "Winehouse" will be passed as an unique argument called `artist_name` to the neuron.
+
+If you want to send more than one argument, you must split your argument with a word that Kalliope will use to recognise the start and the end of each arguments.
+For example:  "give me the weather at {{ location }} for {{ date }}"
+And the order would be: "give me the weather at Paris for tomorrow"
+And so, it will word too with: "give me the weather at St-Pierre de Chartreuse for tomorrow"
+
+See the **input values** section of the [neuron documentation](neurons) to know how to send argument to a neuron.
+
+>**Important note:** The following syntax cannot be used: "<sentence> {{ arg_name }} {{ arg_name2 }}" as Kalliope cannot know when a block starts and when it finishes.
+
 ## Event
 
 An event is a way to schedule the launching of a synapse periodically at fixed times, dates, or intervals.