From 0287e595e7f9e4cc36b9cb939e5238b1b892d831 Mon Sep 17 00:00:00 2001 From: Matheus Brasil Date: Fri, 23 Oct 2015 17:59:00 -0200 Subject: [PATCH 1/4] Put license in markdown --- LICENSE => LICENSE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename LICENSE => LICENSE.md (99%) diff --git a/LICENSE b/LICENSE.md similarity index 99% rename from LICENSE rename to LICENSE.md index e1423e9..c53ad31 100644 --- a/LICENSE +++ b/LICENSE.md @@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. \ No newline at end of file +SOFTWARE. From 238f5a61624a0f043bd3ade889b19c35132083b6 Mon Sep 17 00:00:00 2001 From: Matheus Brasil Date: Fri, 23 Oct 2015 18:05:46 -0200 Subject: [PATCH 2/4] Add some contributing guidelines --- CONTRIBUTING.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b3e4643 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,29 @@ +#Contributing + +##Table of Contents + +- [Reporting a bug](#reporting-a-bug) +- [The 5 magic steps](#the-5-magic-steps) +- [License](#license) + +##Reporting a bug + +1. Look for any related issues [here](https://github.com/daffl/mysam/issues). +2. If you find an issue that seems related, please comment there instead of creating a new issue. If it is determined to be a unique bug, we will let you know that a new issue can be created. +3. If you find no related issue, create a new issue by clicking [here](https://github.com/daffl/mysam/issues/new). +If we find an issue that's related, we will reference it and close your issue, showing you where to follow the bug. +4. Tell us important details like what operating system you are using. +5. Include any errors that may be displayed. +6. Update us if you have any new info, or if the problem resolves itself! + +##The 5 magic steps + +1. Fork it! +2. Create your feature branch: `git checkout -b my-new-feature` +3. Commit your changes: `git commit -m 'Add some feature'` +4. Push to the branch: `git push origin my-new-feature` +5. Submit a pull request :) + +##License + +[MySam](https://github.com/daffl/mysam) is distributed under the MIT License, [available in this repository](master/LICENSE.md). All contributions are assumed to be also licensed under the same. From f8cba520db1a575c5c41228fbdb05e18554ce200 Mon Sep 17 00:00:00 2001 From: Matheus Brasil Date: Fri, 23 Oct 2015 18:16:22 -0200 Subject: [PATCH 3/4] Fix contributing.md --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3e4643..722892d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,12 @@ -#Contributing +# Contributing -##Table of Contents +## Table of Contents - [Reporting a bug](#reporting-a-bug) - [The 5 magic steps](#the-5-magic-steps) - [License](#license) -##Reporting a bug +## Reporting a bug 1. Look for any related issues [here](https://github.com/daffl/mysam/issues). 2. If you find an issue that seems related, please comment there instead of creating a new issue. If it is determined to be a unique bug, we will let you know that a new issue can be created. @@ -24,6 +24,6 @@ If we find an issue that's related, we will reference it and close your issue, s 4. Push to the branch: `git push origin my-new-feature` 5. Submit a pull request :) -##License +## License [MySam](https://github.com/daffl/mysam) is distributed under the MIT License, [available in this repository](master/LICENSE.md). All contributions are assumed to be also licensed under the same. From 30b28304a46b34048e6bc011bb1d48b0e40cd383 Mon Sep 17 00:00:00 2001 From: Matheus Brasil Date: Fri, 23 Oct 2015 18:24:36 -0200 Subject: [PATCH 4/4] General readme.md changes This just suggests a better docs organization: - All section titles in Title Case - Adds a table of contents - Organize the CLI available flags in a table - Change some sections order - Use `$ ...` insted of > ... for CLI instructions - Adds new plugins instructions as in #4 --- readme.md | 191 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 110 insertions(+), 81 deletions(-) diff --git a/readme.md b/readme.md index 05da4ce..bcccfae 100644 --- a/readme.md +++ b/readme.md @@ -1,28 +1,38 @@ -# Say hi SAM +# Say *hi*, SAM -[ ![Codeship Status for daffl/mysam](https://codeship.com/projects/b26a3f10-3c66-0133-d19d-1276d5d0a1e7/status?branch=master)](https://codeship.com/projects/102258) +[![Codeship Status for daffl/mysam](https://codeship.com/projects/b26a3f10-3c66-0133-d19d-1276d5d0a1e7/status?branch=master)](https://codeship.com/projects/102258) -Sam is an open-source, web-based "intelligent" assistant. It can listen to you, learn new actions and is extensible with JavaScript plugins. Sam runs a [NodeJS](https://nodejs.org/en/) server and in any modern browser or as an [Electron](http://electron.atom.io/) desktop application. +> Sam is an open-source, web-based *"intelligent"* assistant. It can listen to you, learn new actions and is extensible with JavaScript plugins. Sam runs a [NodeJS](https://nodejs.org/en/) server and in any modern browser or as an [Electron](http://electron.atom.io/) desktop application. Watch this video to see what Sam can do: [![MySam video](http://daffl.github.io/mysam/mysam-video.png)](https://www.youtube.com/watch?v=VxFtSsCM_bo) -# Installation +## Table of Contents + +- [Installation](#installation) +- [Getting Started](#getting-started) +- [Using the CLI](#using-the-cli) +- [Plugins](#plugins) + - [Creating Plugins](#creating-plugins) +- [Contributing](#contributing) +- [License](#license) + +## Installation Install Sam globally with: -> npm install mysam -g +`$ npm install mysam -g` And then run either the desktop application with: -> mysam +`$ mysam` Or the server only (which will be available at [localhost:9090](http://localhost:9090)) via: -> mysam --server +`$ mysam --server` -# Getting started +## Getting Started At first startup Sam will load the basic frontend training data (like learning your name, provide help, saying hi or to learn something new) and ask for your name. @@ -30,26 +40,28 @@ To talk to Sam press *CTRL + SPACE* (make sure the window is focused). All inputs can be submitted with *CTRL + ENTER* (when not in a textarea). -# Plugins +## Using the CLI -All plugins are available on NPM. To ask Sam about the weather run: +The following command line options are available: -> npm install mysam-weather -g +| Flags | Description | +|-------------------|---------------------------| +| `-s`, `--server` | Start server mode only | +| `-d`, `--develop` | Start in development mode | -Then restart the application and ask something like +Development mode (`--develop`) will load the development tools in the Electron application, output detailed log messages to the command line and load the frontend in individual modules. This is helpful when creating your own plugins. -> What's the weather in Berlin? +## Plugins -# Using the CLI +All plugins are available on NPM. To ask Sam about the weather run: -The following command line options are available: +`$ npm install mysam-weather -g` -- __-s, --server__ - Start server mode only -- __-d, --develop__ - Start in development mode +Then restart the application and ask something like -Development mode (`--develop`) will load the development tools in the Electron application, output detailed log messages to the command line and load the frontend in individual modules. This is helpful when creating your own plugins. +> What's the weather in Berlin? -# Creating plugins +### Creating Plugins To create a new plugin create a new folder with the following `package.json`: @@ -60,79 +72,96 @@ To create a new plugin create a new folder with the following `package.json`: "mysam": { "client": "frontend", "styles": "styles.css" - } + }, + "keywords": [ + "mysam-plugin" + ] } ``` - -In the same folder a `server.js` like this: - -```js -module.exports = function(sam) { - // on the server, `sam` is a Feathers application so - // for example we can create new actions like this: - sam.service('actions').create({ - text: 'Ping from my plugin', - tags: [], - action: { - type: 'myplugin', - ping: 'Default ping' - } - }, function(error, data) { - console.log('Created', data); - }); -}; -``` - -And a `frontend.js` like this: - -```js -module.exports = function(sam) { - // sam is the client side application instance - // which you can register new actions like this: - sam.action('myplugin', function(element, classification) { - // element is the jQuery wrapped main element - // classification is an object with information about the - // text that triggered this action - var heading = document.createElement('h1'); - heading.className = 'myplugin'; - heading.innerHTML = 'Hello from my plugin: ' + classification.action.ping; - - element.html(heading); - }); - - // and learners (which will also show up in the help) like this - sam.learn({ - description: 'Call myplugin', - tags: ['name'], - form: function(el, save) { - el.html('') - .on('submit', function(save) { - save({ - type: 'myplugin', - ping: el.find('.param').val() +> **Note**: It is important to add the `mysam-plugin` keyword to your `package.json` +file to ensure that your plugin will be shown in *MySam*'s plugins catalog. + +- In the same folder a `server.js` like this: + + ```js + module.exports = function(sam) { + // on the server, `sam` is a Feathers application so + // for example we can create new actions like this: + sam.service('actions').create({ + text: 'Ping from my plugin', + tags: [], + action: { + type: 'myplugin', + ping: 'Default ping' + } + }, function(error, data) { + console.log('Created', data); + }); + }; + ``` + +- And a `frontend.js` like this: + + ```js + module.exports = function(sam) { + // sam is the client side application instance + // which you can register new actions like this: + sam.action('myplugin', function(element, classification) { + // element is the jQuery wrapped main element + // classification is an object with information about the + // text that triggered this action + var heading = document.createElement('h1'); + heading.className = 'myplugin'; + heading.innerHTML = 'Hello from my plugin: ' + classification.action.ping; + + element.html(heading); + }); + + // and learners (which will also show up in the help) like this + sam.learn({ + description: 'Call myplugin', + tags: ['name'], + form: function(el, save) { + el.html('') + .on('submit', function(save) { + save({ + type: 'myplugin', + ping: el.find('.param').val() + }); }); - }); - } - }); -}; -``` + } + }); + }; + ``` -`styles.css` can contain any CSS styles: +- `styles.css` can contain any CSS styles: -```css -.myplugin { - font-size: 4em; -} -``` + ```css + .myplugin { + font-size: 4em; + } + ``` + +> You'll soon have a [Yeoman](http://yeoman.io/) generator for new plugins +that initialize everything similar to what is described above so that you can +just do `$ mysam create my-plugin`. To use the plugin run -> npm link +`$ npm link` in the plugin folder and restart the application (for easier debugging you can use the `--develop` flag). -Now saying something like +Now saying something like: -> Can I get a ping from my plugin please? +> *Can I get a ping from my plugin please?* Should show the element we created in the action. + +## Contributing + +Contributions are very welcome! If you'd like to contribute, these [guidelines](CONTRIBUTING.md) may help you. + +## License + +[MySam](https://github.com/daffl/mysam) is distributed under the MIT License, [available in this repository](master/LICENSE.md). All contributions are assumed to be also licensed under the same.