Browse Source

[Doc] draft contributing.md

monf 8 years ago
parent
commit
aa9dd7be50
2 changed files with 80 additions and 7 deletions
  1. 79 6
      Docs/contributing.md
  2. 1 1
      core/NeuronModule.py

+ 79 - 6
Docs/contributing.md

@@ -1,16 +1,89 @@
 # Contributing
 
-## TODOs
+Kalliope needs the community to improve its Core features and to create new Neurons. Let's join us !
 
-Here is the todo list we've made from our own ideas or from the community.
+## Core
 
-- todo 1
-- todo 2
+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
+5. Submit a pull request :D
+
+
+## Neurons
+
+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.
+
+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. (*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.
+
+##### 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.
+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.
+
+##### 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!)
+    - 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

+ 1 - 1
core/NeuronModule.py

@@ -17,7 +17,7 @@ logger = logging.getLogger("kalliope")
 
 class InvalidParameterException(Exception):
     """
-   Some Neuron parameters are invalid.
+    Some Neuron parameters are invalid.
     """
     pass