diff --git a/.gitignore b/.gitignore index 1576f8e..3568e02 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ .* *egg-info dist +README.html diff --git a/README.rst b/README.rst index a9e3514..cbd7277 100644 --- a/README.rst +++ b/README.rst @@ -1,26 +1,29 @@ -.. image:: logo.png +.. image:: img/header.png :height: 6em - :align: left + :target: http://demos.gsi.dit.upm.es/senpy -===================================== -`Senpy `_ -===================================== .. image:: https://travis-ci.org/gsi-upm/senpy.svg?branch=master - :target: https://travis-ci.org/gsi-upm/senpy + :target: https://travis-ci.org/gsi-upm/senpy -Sentiment analysis web services using a common interface: NIF+JSON-LD. +Senpy lets you create sentiment analysis web services easily, fast and using a well known API. +As a bonus, senpy services use semantic vocabularies (e.g. `NIF `_, `Marl `_, `Onyx `_) and formats (turtle, JSON-LD, xml-rdf). -With Senpy, you can easily turn your sentiment analysis algorithm into a web service, just by creating a new plugin. +Have you ever wanted to turn your sentiment analysis algorithms into a service? +With senpy, now you can. +It provides all the tools so you just have to worry about improving your algorithms: -`DEMO on Heroku `_ +`See it in action. `_ Installation ------------ -The stable version can be installed via pip: +The stable version can be installed in three ways. + +Through PIP +*********** .. code:: bash - pip install senpy + pip install --user senpy Alternatively, you can use the development version: @@ -29,31 +32,19 @@ Alternatively, you can use the development version: git clone git@github.com:gsi-upm/senpy cd senpy - pip install -r requirements.txt - -To install it system-wide, use setuptools: - -.. code:: bash - - python setup.py install - - -If you are using docker, build the image or use the pre-built one: - -.. code:: bash + pip install --user . - docker run -ti -p 5000:5000 balkian/senpy --host 0.0.0.0 --default-plugins +If you want to install senpy globally, use sudo instead of the ``--user`` flag. -To add custom plugins, add a volume and tell senpy where to find the plugins: - -.. code:: bash +Docker Image +************ +Build the image or use the pre-built one: ``docker run -ti -p 5000:5000 balkian/senpy --host 0.0.0.0 --default-plugins``. - docker run -ti -p 5000:5000 -v :/plugins balkian/senpy --host 0.0.0.0 --default-plugins -f /plugins`` -Using +Usage ----- -You can use the modules included in senpy to build your own application. However, the easiest and recommended way is to just use the command-line tool to load your plugins and launch the server. .. code:: bash @@ -70,27 +61,31 @@ or, alternatively: This will create a server with any modules found in the current path. For more options, see the `--help` page. +Alternatively, you can use the modules included in senpy to build your own application. -TO-DO ------ +Deploying on Heroku +------------------- +Use a free heroku instance to share your service with the world. +Just use the example Procfile in this repository, or build your own. + + +`DEMO on heroku `_ -* Improve documentation and generate it with Sphinx -* ReadTheDocs -* Improve README + +For more information, check out the `documentation `_. +------------------------------------------------------------------------------------ Acknowledgement --------------- -EUROSENTIMENT PROJECT -Grant Agreement no: 296277 -Starting date: 01/09/2012 -Project duration: 24 months - -.. image:: logo_grande.png - :target: logo_grande.png - :width: 100px - :alt: Eurosentiment Logo - -.. image:: logo_fp7.gif - :width: 100px - :target: logo_fp7.gif +This development has been partially funded by the European Union through the MixedEmotions Project (project number H2020 655632), as part of the `RIA ICT 15 Big data and Open Data Innovation and take-up` programme. + + +.. image:: img/me.png + :target: http://mixedemotions-project.eu + :height: 100px + :alt: MixedEmotions Logo + +.. image:: img/eu-flag.jpg + :height: 100px + :target: http://ec.europa.eu/research/participants/portal/desktop/en/opportunities/index.html diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..e35d885 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..33aab2c --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,208 @@ +NIF API +======= +.. http:get:: /api + + Basic endpoint for sentiment/emotion analysis. + + **Example request**: + + .. sourcecode:: http + + GET /api?input=I%20love%20GSI HTTP/1.1 + Host: localhost + Accept: application/json, text/javascript + + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: text/javascript + + { + "@context": [ + "http://127.0.0.1/static/context.jsonld", + ], + "analysis": [ + { + "@id": "SentimentAnalysisExample", + "@type": "marl:SentimentAnalysis", + "dc:language": "en", + "marl:maxPolarityValue": 10.0, + "marl:minPolarityValue": 0.0 + } + ], + "domain": "wndomains:electronics", + "entries": [ + { + "opinions": [ + { + "prov:generatedBy": "SentimentAnalysisExample", + "marl:polarityValue": 7.8, + "marl:hasPolarity": "marl:Positive", + "marl:describesObject": "http://www.gsi.dit.upm.es", + } + ], + "nif:isString": "I love GSI", + "strings": [ + { + "nif:anchorOf": "GSI", + "nif:taIdentRef": "http://www.gsi.dit.upm.es" + } + ] + } + ] + } + + :query i input: No default. Depends on informat and intype + :query f informat: one of `turtle` (default), `text`, `json-ld` + :query t intype: one of `direct` (default), `url` + :query o outformat: one of `turtle` (default), `text`, `json-ld` + :query p prefix: prefix for the URIs + :query algo algorithm: algorithm/plugin to use for the analysis. For a list of options, see :http:get:`/api/plugins`. If not provided, the default plugin will be used (:http:get:`/api/plugins/default`). + + :reqheader Accept: the response content type depends on + :mailheader:`Accept` header + :resheader Content-Type: this depends on :mailheader:`Accept` + header of request + :statuscode 200: no error + :statuscode 404: service not found + +.. http:post:: /api + + The same as :http:get:`/api`. + +.. http:get:: /api/plugins + + Returns a list of installed plugins. + **Example request**: + + .. sourcecode:: http + + GET /api/plugins HTTP/1.1 + Host: localhost + Accept: application/json, text/javascript + + + **Example response**: + + .. sourcecode:: http + + { + "@context": { + ... + }, + "sentiment140": { + "name": "sentiment140", + "is_activated": true, + "version": "0.1", + "extra_params": { + "@id": "extra_params_sentiment140_0.1", + "language": { + "required": false, + "@id": "lang_sentiment140", + "options": [ + "es", + "en", + "auto" + ], + "aliases": [ + "language", + "l" + ] + } + }, + "@id": "sentiment140_0.1" + }, + "rand": { + "name": "rand", + "is_activated": true, + "version": "0.1", + "extra_params": { + "@id": "extra_params_rand_0.1", + "language": { + "required": false, + "@id": "lang_rand", + "options": [ + "es", + "en", + "auto" + ], + "aliases": [ + "language", + "l" + ] + } + }, + "@id": "rand_0.1" + } + } + + +.. http:get:: /api/plugins/ + + Returns the information of a specific plugin. + **Example request**: + + .. sourcecode:: http + + GET /api/plugins/rand HTTP/1.1 + Host: localhost + Accept: application/json, text/javascript + + + **Example response**: + + .. sourcecode:: http + + { + "@id": "rand_0.1", + "extra_params": { + "@id": "extra_params_rand_0.1", + "language": { + "@id": "lang_rand", + "aliases": [ + "language", + "l" + ], + "options": [ + "es", + "en", + "auto" + ], + "required": false + } + }, + "is_activated": true, + "name": "rand", + "version": "0.1" + } + + +.. http:get:: /api/plugins/default + + Return the information about the default plugin. + +.. http:get:: /api/plugins//{de}activate + + {De}activate a plugin. + + **Example request**: + + .. sourcecode:: http + + GET /api/plugins/rand/deactivate HTTP/1.1 + Host: localhost + Accept: application/json, text/javascript + + + **Example response**: + + .. sourcecode:: http + + { + "@context": {}, + "message": "Ok" + } diff --git a/docs/conf.py b/docs/conf.py index c6c1a4b..6cc85a9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,6 +34,7 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', + 'sphinxcontrib.httpdomain', 'sphinx.ext.coverage', ] diff --git a/docs/index.rst b/docs/index.rst index cf4f623..0a96f9d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,14 +9,8 @@ Welcome to Senpy's documentation! Contents: .. toctree:: + installation + usage + api + plugins :maxdepth: 2 - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..69f52f6 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,27 @@ +Installation +------------ +The stable version can be installed in three ways. + +Through PIP +*********** + +.. code:: bash + + pip install --user senpy + + +Alternatively, you can use the development version: + +.. code:: bash + + git clone git@github.com:gsi-upm/senpy + cd senpy + pip install --user . + +If you want to install senpy globally, use sudo instead of the ``--user`` flag. + +Docker Image +************ +Build the image or use the pre-built one: ``docker run -ti -p 5000:5000 balkian/senpy --host 0.0.0.0 --default-plugins``. + +To add custom plugins, add a volume and tell senpy where to find the plugins: ``docker run -ti -p 5000:5000 -v :/plugins balkian/senpy --host 0.0.0.0 --default-plugins -f /plugins`` diff --git a/docs/plugins.rst b/docs/plugins.rst new file mode 100644 index 0000000..4787c87 --- /dev/null +++ b/docs/plugins.rst @@ -0,0 +1,4 @@ +Developing new plugins +---------------------- + +See the examples at: ``_. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..0e47a20 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +sphinxcontrib-httpdomain>=1.4 diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..072cbf1 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,20 @@ +Usage +----- + +The easiest and recommended way is to just use the command-line tool to load your plugins and launch the server. + +.. code:: bash + + senpy + +Or, alternatively: + +.. code:: bash + + python -m senpy + + +This will create a server with any modules found in the current path. +For more options, see the `--help` page. + +Alternatively, you can use the modules included in senpy to build your own application. diff --git a/img/eu-flag.jpg b/img/eu-flag.jpg new file mode 100644 index 0000000..ceaad60 Binary files /dev/null and b/img/eu-flag.jpg differ diff --git a/img/final-logo.svg b/img/final-logo.svg new file mode 100644 index 0000000..c2a9c0a --- /dev/null +++ b/img/final-logo.svg @@ -0,0 +1,828 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + py + Senpy + + + + + + + + py + Senpy + + + + + + + + py + Senpy + diff --git a/img/gsi.png b/img/gsi.png new file mode 100644 index 0000000..6ab93de Binary files /dev/null and b/img/gsi.png differ diff --git a/img/header.png b/img/header.png new file mode 100644 index 0000000..a597406 Binary files /dev/null and b/img/header.png differ diff --git a/logo.png b/img/logo.png similarity index 100% rename from logo.png rename to img/logo.png diff --git a/logo.svg b/img/logo.svg similarity index 100% rename from logo.svg rename to img/logo.svg diff --git a/logo_grande.png b/img/logo_grande.png similarity index 100% rename from logo_grande.png rename to img/logo_grande.png diff --git a/img/me.png b/img/me.png new file mode 100644 index 0000000..fb682e6 Binary files /dev/null and b/img/me.png differ