Started readthedocs and improved README

.gitignore

@@ -2,3 +2,4 @@
 .*
 *egg-info
 dist
+README.html

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 <http://senpy.herokuapp.com>`_
-=====================================
 .. 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 <http://persistence.uni-leipzig.org/nlp2rdf/>`_, `Marl <http://www.gsi.dit.upm.es/ontologies/marl>`_, `Onyx <http://www.gsi.dit.upm.es/ontologies/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 <http://senpy.herokuapp.com>`_
+`See it in action. <http://demos.gsi.dit.upm.es/senpy>`_
 
 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:
+   pip install --user .
 
-.. code:: bash
+If you want to install senpy globally, use sudo instead of the ``--user`` flag.
 
-   python setup.py install
+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 <PATH OF PLUGINS>:/plugins balkian/senpy --host 0.0.0.0 --default-plugins -f /plugins``
 
-If you are using docker, build the image or use the pre-built one:
-
-.. code:: bash
-
-    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:
-   
-.. code:: bash
-
-    docker run -ti -p 5000:5000 -v <PATH OF PLUGINS:/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.
 
-* Improve documentation and generate it with Sphinx
-* ReadTheDocs
-* Improve README
+
+`DEMO on heroku <http://senpy.herokuapp.com>`_
+
+
+For more information, check out the `documentation <http://senpy.readthedocs.org>`_.
+------------------------------------------------------------------------------------
 
 
 Acknowledgement
 ---------------
-EUROSENTIMENT PROJECT
-Grant Agreement no: 296277
-Starting date: 01/09/2012
-Project duration: 24 months
+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:: logo_grande.png
-    :target: logo_grande.png
-    :width: 100px
-    :alt: Eurosentiment Logo
 
-.. image:: logo_fp7.gif
-    :width: 100px
-    :target: logo_fp7.gif
+.. 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

docs/.gitignore

@@ -0,0 +1 @@
+_build

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/<pluginname>
+
+   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/<pluginname>/{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"
+       }

docs/conf.py

@@ -34,6 +34,7 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'sphinx.ext.todo',
+    'sphinxcontrib.httpdomain',
     'sphinx.ext.coverage',
 ]
 

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`
-

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 <PATH OF PLUGINS>:/plugins balkian/senpy --host 0.0.0.0 --default-plugins -f /plugins``

docs/plugins.rst

@@ -0,0 +1,4 @@
+Developing new plugins
+----------------------
+
+See the examples at: `<http://github.com/gsi-upm/senpy-plugins-community>`_.

docs/requirements.txt

@@ -0,0 +1 @@
+sphinxcontrib-httpdomain>=1.4

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.