Selaa lähdekoodia

Merge pull request #151 from kalliope-project/dev_nico

update doc for v0.4.0
Monf 8 vuotta sitten
vanhempi
commit
b1b16f009d

+ 17 - 111
Docs/contributing.md

@@ -1,120 +1,32 @@
 # Contributing
 
-Kalliope needs the community to improve its Core features and to create new Neurons. Let's join us !
+Kalliope needs the community to improve its Core features and to create new Neurons, STTs, TTSs. Let's join us !
+[Here is the Todo list](https://trello.com/b/H0TecLSi/kalliopecore) if you are looking for some ideas.
 
 ## Core
 
 The community can contribute to the Core of Kalliope by providing some new features.
 
-#### How to contribute
+**How to contribute**
 
 1. Fork it!
-2. Create your feature branch: `git checkout -b my-new-feature`
-3. Commit your changes: `git commit -am 'Add some feature'`
-4. Push to the branch: `git push origin my-new-feature`
-5. Submit a pull request :D
+1. Checkout the dev branch `git checkout dev`
+1. Create your feature branch: `git checkout -b my-new-feature`
+1. Commit your changes: `git commit -am 'Add some feature'`
+1. Push to the branch: `git push origin my-new-feature`
+1. Submit a pull request in the **dev** branch
 
+## Community module (Neuron, STT, TTS)
 
-## Neurons
+Kalliope comes with a community [installation command](kalliope_cli.md). Your can create a module in you own git repo that will be available to all Kalliope users.
 
-Kalliope modularity is fully based on Neuron so the community can contribute by adding their own.
-Neurons are independent projects so they can be developed under a github project. Anyone can clone them, place them under the neurons repository and reuse them.
+See the dedicated documentation depending on the type of module you want to code.
+- create a [community neuron](contributing/contribute_neuron.md)
+- create a [community STT](contributing/contribute_stt.md)
+- create a [community TTS](contributing/contribute_tts.md)
 
-Creating a new Neuron must follow some rules:
 
-##### Repository Structure
-1. The Neuron repository name is in __lowercase__.
-1. The Neuron repository must be added under the __neurons__ repository coming from the Core. 
-1. Under the Neuron repository, the Neuron has a __README.md file__ describing the Neuron following this structure:
-    - Neuron name:
-    - Synopsis:         Description of the Neuron
-    - Options:          A table of the incoming parameters managed by the Neuron.
-    - Return Values:    A table of the returned values which can be catched by the *say_template attribute*.
-    - Synapses example: An example of how to use the Neuron inside a Synapse.
-    - Notes:            Something which needs to be add.
-1. Under the Neuron repository, include a __Tests repository__ to manage the test of the Neuron.
-
-    
-##### Code
-1. Under the Neuron repository, the Neuron file name .py is also in __lowercase__.
-1. The Neuron must be coded in __Python 2.7__.
-1. Under the Neuron repository, include the __init__.py file which contains: *from neuron import Neuron* (/!\ respect the Case)
-1. Inside the Neuron file, the Neuron Class name is in __uppercase__.
-1. The Neuron __inherits from the NeuronModule__ coming from the Core. 
-
-    ```
-    from core.NeuronModule import NeuronModule
-    class Say(NeuronModule):
-    ```
-
-
-1. The Neuron has a constructor __init__ which is the entry point.
-The constructor has a __**kwargs argument__ which is corresponding to the Dict of incoming variables:values defined either in the brain file or in the signal.
-1. The Neuron must refer to its __parent structure__ in the init by calling the super of NeuronModule.
-  
-    ```
-    def __init__(self, **kwargs):
-        super(Say, self).__init__(**kwargs)
-    ```
-
-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
-    ```
-
-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:
-    - MissingParameterException: *Some Neuron parameters are missing.*
-    - InvalidParameterException: *Some Neuron parameters are invalid.*
-
-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)
-        # the 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 language__ inside its own logic.
-Only [Synapse](brain.md) by the use of [Order](signals.md) must interact with the languages. This allow a Neuron to by reused by anyone, speaking any language.
+## Constraints
 
 1. Respect [PEP 257](https://www.python.org/dev/peps/pep-0257/) -- Docstring conventions. For each class or method add a description with summary, input parameter, returned parameter,  type of parameter
     ```
@@ -131,17 +43,11 @@ We recommend the usage of an IDE like [Pycharm](https://www.jetbrains.com/pychar
 
 ##### Limitations
 
-1. The management of incoming variable from the signal order when they are __numbers or float are not efficient__. (Thanks to @thebao for pointing this out!)
+1. The management of incoming variable from the signal order when they are __numbers or float are not efficient__.
     - Because of the differences between the STTs outputs: some are returning word some numbers (two != 2). 
     - Because of the i18n, we are not able to know if a variable should be  interpreted in english, french, spanish, etc ... ("two" != "deux" != "dos")
 
 
-## STT, TTS, Trigger
-
-They are managed like Neurons, you can follow the same process to develop your own !
-
 ## Share it
 
-*Incoming*
-
-We are maintening a list of all the Neurons available from the community, let us know
+We are maintening a list of all the Neurons available from the community, let us know you've developed your own by opening [an issue](../../issues) with the link of your neuron or send a pull request to update the [neuron list](neuron_list.md) directly.

+ 104 - 0
Docs/contributing/contribute_neuron.md

@@ -0,0 +1,104 @@
+# Contributing: Create a neuron
+
+Neurons are independent projects so they can be developed under a github project. Anyone can clone them, place them under the neurons repository and reuse them.
+
+Creating a new Neuron must follow some rules:
+
+## Repository Structure
+1. The Neuron repository name is in __lowercase__.
+1. Under the Neuron repository, the Neuron has a __README.md file__ describing the Neuron following this structure. You can get a [template here](../neuron_template.md):
+    - Neuron name:
+    - Installation:     The CLI command used to install the neuron
+    - Synopsis:         Description of the Neuron
+    - Options:          A table of the incoming parameters managed by the Neuron.
+    - Return Values:    A table of the returned values which can be catched by the *say_template attribute*.
+    - Synapses example: An example of how to use the Neuron inside a Synapse.
+    - Notes:            Something which needs to be add.
+1. Under the Neuron repository, include a __Tests repository__ to manage the test of the Neuron.
+1. Under the neuron repository, a [dna.yml file](dna.md) must be added that contains information about the neuron.
+1. Under the neuron repository, a [install.yml file](installation_file.md) must be added that contains the installation process.
+
+
+## Code
+1. Under the Neuron repository, the Neuron file name .py is also in __lowercase__.
+1. The Neuron must be coded in __Python 2.7__.
+1. Under the Neuron repository, include the __init__.py file which contains: *from neuron import Neuron* (/!\ respect the Case)
+1. Inside the Neuron file, the Neuron Class name is in __uppercase__.
+1. The Neuron __inherits from the NeuronModule__ coming from the Core.
+
+    ```
+    from core.NeuronModule import NeuronModule
+    class Say(NeuronModule):
+    ```
+
+
+1. The Neuron has a constructor __init__ which is the entry point.
+The constructor has a __**kwargs argument__ which is corresponding to the Dict of incoming variables:values defined either in the brain file or in the signal.
+1. The Neuron must refer to its __parent structure__ in the init by calling the super of NeuronModule.
+
+    ```
+    def __init__(self, **kwargs):
+        super(Say, self).__init__(**kwargs)
+    ```
+
+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
+    ```
+
+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:
+    - MissingParameterException: *Some Neuron parameters are missing.*
+    - InvalidParameterException: *Some Neuron parameters are invalid.*
+
+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. The Neuron must (as much as possible) ensure the i18n. This means that they should __not manage a specific language__ inside its own logic.
+Only [Synapse](brain.md) by the use of [Order](signals.md) must interact with the languages. This allow a Neuron to by reused by anyone, speaking any language.
+
+
+## Code example
+
+Example of neuron structure
+```
+myneuron/
+├── __init__.py
+├── myneuron.py
+├── dna.yml
+├── install.yml
+├── README.md
+└── tests
+    ├── __init__.py
+    └── test_myneuron.py
+```
+
+Example of neuron code
+```
+class Myneuron(NeuronModule):
+def __init__(self, **kwargs):
+    super(Myneuron, self).__init__(**kwargs)
+    # the 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
+```

+ 1 - 0
Docs/contributing/contribute_stt.md

@@ -0,0 +1 @@
+# Contributing: Create a STT

+ 1 - 0
Docs/contributing/contribute_tts.md

@@ -0,0 +1 @@
+# Contributing: Create a TTS

+ 30 - 0
Docs/contributing/dna.md

@@ -0,0 +1,30 @@
+# dna.yml file
+
+The dna file is the descriptor of your module.
+This file has a yaml syntax and must be present to allow Kalliope to install it from the [CLI](../kalliope_cli.md).
+
+## DNA parameters
+
+| parameter                  | type   | required | default | choices          | comment                                                                                                                               |
+|----------------------------|--------|----------|---------|------------------|---------------------------------------------------------------------------------------------------------------------------------------|
+| name                       | string | yes      |         |                  | Lowercase. It will be the name of the folder installed in ressources_dir for the target type of resource                              |
+| type                       | string | yes      |         | neuron, stt, tts | The type of resource. This will be used by Kalliope install process to place the resource in the right directory set in resources_dir |
+| author                     | string | no       |         |                  | String that contain info about the author of the modul like a name or a github profile page                                           |
+| kalliope_supported_version | list   | yes      |         | 0.4.0            | list of kalliope version the module support. E.g `- 0.4.0`                                                                            |
+| tags                       | list   | no       |         |                  | list of tags that can help to categorize the module. E.g: "email", "social network", "search engine"                                  |
+
+## DNA file examples
+
+A dna file for a neuron
+```
+name: "wikipedia_searcher"
+type: "neuron"
+author: "The dream team of Kalliope project"
+
+kalliope_supported_version:
+  - "0.4.0"
+
+tags:
+  - "search engine"
+  - "wiki"
+```

+ 53 - 0
Docs/contributing/installation_file.md

@@ -0,0 +1,53 @@
+# install.yml file
+
+The installation file, called install.yml, must be placed at the root of a repository. This one will be read by Kalliope in order to install your module from the [command line](../kalliope_cli.md) by any Kalliope user.
+
+## How to create an install.yml file
+
+The module installation process is based on the Ansible program. Ansible is an IT orchestrator. It means it can help you to perform configuration management, application deployment or task automation.
+
+The `install.yml` file must contains what we called a Playbook in the Ansible world.
+A playbook is like a recipe or an instructions manual which tells Ansible what to do against an host. In our case, the host will be the local machine of the current user who asked Kalliope to install the module.
+
+Let's see a basic playbook, the one used by the neuron [wikipedia_searcher](https://github.com/kalliope-project/kalliope_neuron_wikipedia)
+
+```
+- name: Kalliope wikipedia_searcher neuron install
+  hosts: localhost
+  gather_facts: no
+  connection: local
+  become: true
+
+  tasks:
+    - name: "Install pip dependencies"
+      pip:
+        name: wikipedia
+        version: 1.4.0
+```
+
+As the file is a **playbook**, it can contains multiple **play**. That's why the file start with a "-", the yaml syntax to define a list of element. In this example, our playbook contains only one play.
+
+The first element is the `name`. It can be anything you want. Here we've set what the play do.
+
+The `hosts` parameter is, like the name sugest us, to design on which host we want to apply our configuration. In the context of a Kalliope module installation, it will always be **localhost**.
+
+By default, ansible call a module to [gather useful variables](http://docs.ansible.com/ansible/setup_module.html) about remote hosts that can be used in playbooks.
+In this example, we don't need it and so we disable the `gather_facts` feature in order to win a couple seconds during the installation process.
+
+In most of case, our play will need to apply admin operations. In this case, installing a python lib. So we set `become` to true to be allowed to install our lib as root user.
+
+The next part is `tasks`. This key must contains a list of task to apply on the target system.
+
+The only task we've added here is based on the [pip Ansible module](http://docs.ansible.com/ansible/pip_module.html).
+
+Ansible comes with a lot of modules, see the [complete list here](http://docs.ansible.com/ansible/modules_by_category.html).
+
+Here is an example which use the [apt module](http://docs.ansible.com/ansible/apt_module.html) to install Debian packages
+```
+tasks:
+  - name: Install packages
+    apt: name={{ item }} update_cache=yes
+    with_items:
+      - flac
+      - mplayer
+```

+ 18 - 1
Docs/kalliope_cli.md

@@ -32,6 +32,19 @@ Example of use
 kalliope gui
 ```
 
+### install
+Install a community module. You must set an install type option. Currently the only available option is `--git-url`.
+
+Syntax
+```
+kalliope install --git-url "<url>"
+```
+
+Example of use
+```
+kalliope install --git-url "https://github.com/kalliope-project/kalliope_neuron_wikipedia.git"
+```
+
 ## OPTIONS
 
 Commands can be completed by the following options:
@@ -67,4 +80,8 @@ Show debug output in the console
 Example of use
 ```
 kalliope start --debug
-```
+```
+
+### --git-url
+
+Used by the `install` argument to specify the URL of a git repository of the module to install.

+ 3 - 0
Docs/signals.md

@@ -28,6 +28,9 @@ signals:
 > **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:** STT engines don't know the context. Sometime they will return an unexpected word.
+For example, "the operation to perform is 2 minus 2" can return "two", "too", "to" or "2" in english.
+
 > **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, 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

+ 6 - 1
README.md

@@ -28,6 +28,11 @@ Kalliope is easy-peasy to use, see the hello world
 
 - [Kalliope installation documentation](Docs/installation.md)
 
+## Quick start
+
+We made starter kits that only needs to be cloned and launched. Starter kits can help you to learn basics of Kalliope
+- [French starter kit](https://github.com/kalliope-project/kalliope_starter_fr)
+- [English starter kit](https://github.com/kalliope-project/kalliope_starter_en)
 
 ## Usage
 
@@ -55,7 +60,7 @@ Kalliope is easy-peasy to use, see the hello world
 If you'd like to contribute to Kalliope, please read our [Contributing Guide](Docs/contributing.md), which contains the philosophies to preserve, tests to run, and more. 
 Reading through this guide before writing any code is recommended.
 
-- Contribute
+- Read the [contributing guide](Docs/contributing.md)
 - Add [issues and feature requests](../../issues)
 
 ## Credits

+ 1 - 1
kalliope/neurons/ansible_playbook/README.md

@@ -73,7 +73,7 @@ In this case, you must give to the neuron the login and password of the user whi
     neurons:
       - ansible_playbook:
           task_file: "playbook-root.yml"
-          sudo: true,
+          sudo: true
           sudo_user: "root"
           sudo_password: "secret"
 ```