Update readthedocs. Mainly Api and What is senpy section

7 years ago · 8b2c3e8d40
parent cc298742ec
commit 8b2c3e8d40
7 changed files with 179 additions and 137 deletions
--- a/docs/api.rst
+++ b/docs/api.rst
@ -22,38 +22,32 @@ NIF API
      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"
-            }
-          ]
-        }
-       ]
+        "@context":"http://127.0.0.1/api/contexts/Results.jsonld",
+        "@id":"_:Results_11241245.22",
+        "@type":"results"
+        "analysis": [
+          "plugins/sentiment-140_0.1" 
+        ],
+        "entries": [
+          {  
+            "@id": "_:Entry_11241245.22"
+            "@type":"entry",
+            "emotions": [],
+            "entities": [],
+            "sentiments": [
+              {  
+                "@id": "Sentiment0",  
+                "@type": "sentiment", 
+                "marl:hasPolarity": "marl:Negative",
+                "marl:polarityValue": 0,
+                "prefix": ""
+              }
+            ],
+            "suggestions": [],
+            "text": "This text makes me sad.\nwhilst this text makes me happy and surprised at the same time.\nI cannot believe it!",
+            "topics": []
+          }
+        ]
      }

   :query i input: No default. Depends on informat and intype
@ -92,58 +86,59 @@ NIF API

   .. sourcecode:: http

-        {
-            "@context": {
-                   ...
-            },
-            "@type": "plugins",
-            "plugins": [
-                  {
-                    "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"
-                }, {
-                    "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"
-                }
-            ]
-        }
-
+      {
+        "@id": "plugins/sentiment-140_0.1", 
+        "@type": "sentimentPlugin", 
+        "author": "@balkian", 
+        "description": "Sentiment classifier using rule-based classification for English and Spanish. This plugin uses sentiment140 data to perform classification. For more information: http://help.sentiment140.com/for-students/", 
+        "extra_params": {
+          "language": {
+            "@id": "lang_sentiment140", 
+            "aliases": [
+              "language", 
+              "l"
+            ], 
+            "options": [
+              "es", 
+              "en", 
+              "auto"
+            ], 
+            "required": false
+          }
+        }, 
+        "is_activated": true, 
+        "maxPolarityValue": 1.0, 
+        "minPolarityValue": 0.0, 
+        "module": "sentiment-140", 
+        "name": "sentiment-140", 
+        "requirements": {}, 
+        "version": "0.1"
+      }, 
+      {
+        "@id": "plugins/ExamplePlugin_0.1", 
+        "@type": "sentimentPlugin", 
+        "author": "@balkian", 
+        "custom_attribute": "42", 
+        "description": "I am just an example", 
+        "extra_params": {
+          "parameter": {
+            "@id": "parameter", 
+            "aliases": [
+              "parameter", 
+              "param"
+            ], 
+            "default": 42, 
+            "required": true
+          }
+        }, 
+        "is_activated": true, 
+        "maxPolarityValue": 1.0, 
+        "minPolarityValue": 0.0, 
+        "module": "example", 
+        "name": "ExamplePlugin", 
+        "requirements": "noop", 
+        "version": "0.1"
+      }

 .. http:get:: /api/plugins/<pluginname>

@ -162,30 +157,60 @@ NIF API
   .. sourcecode:: http

      {
-          "@id": "rand_0.1",
-          "@type": "sentimentPlugin",
-          "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"
+        "@context": "http://127.0.0.1/api/contexts/ExamplePlugin.jsonld", 
+        "@id": "plugins/ExamplePlugin_0.1", 
+        "@type": "sentimentPlugin", 
+        "author": "@balkian", 
+        "custom_attribute": "42", 
+        "description": "I am just an example", 
+        "extra_params": {
+          "parameter": {
+            "@id": "parameter", 
+            "aliases": [
+              "parameter", 
+              "param"
+            ], 
+            "default": 42, 
+            "required": true
+          }
+        }, 
+        "is_activated": true, 
+        "maxPolarityValue": 1.0, 
+        "minPolarityValue": 0.0, 
+        "module": "example", 
+        "name": "ExamplePlugin", 
+        "requirements": "noop", 
+        "version": "0.1"
      }


+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 .. http:get:: /api/plugins/default

   Return the information about the default plugin.
--- a/docs/architecture.rst
+++ b/docs/architecture.rst
@ -0,0 +1,17 @@
+Architecture
+============
+
+The main component of a sentiment analysis service is the algorithm itself. However, for the algorithm to work, it needs to get the appropriate parameters from the user, format the results according to the defined API, interact with the user whn errors occur or more information is needed, etc.
+
+Senpy proposes a modular and dynamic architecture that allows:
+
+* Implementing different algorithms in a extensible way, yet offering a common interface.
+* Offering common services that facilitate development, so developers can focus on implementing new and better algorithms.
+
+The framework consists of two main modules: Senpy core, which is the building block of the service, and Senpy plugins, which consist of the analysis algorithm. The next figure depicts a simplified version of the processes involved in an analysis with the Senpy framework.
+
+.. image:: senpy-architecture.png
+  :height: 400px
+  :width: 800px
+  :scale: 100 %
+  :align: center
--- a/docs/conf.py
+++ b/docs/conf.py
@ -60,10 +60,7 @@ copyright = u'2016, J. Fernando Sánchez'
 # built documents.
 #
 # The short X.Y version.
-with open('../senpy/VERSION') as f:
-    version = f.read().strip()
 # The full version, including alpha/beta/rc tags.
-release = version

 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
--- a/docs/installation.rst
+++ b/docs/installation.rst
@ -22,6 +22,16 @@ 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 gsiupm/senpy --host 0.0.0.0 --default-plugins``.
+Build the image or use the pre-built one:   
+
+    ``docker run -ti -p 5000:5000 gsiupm/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 gsiupm/senpy --host 0.0.0.0 --default-plugins -f /plugins``
+
+
+Note: There is a Senpy version for python2 too.
+    
+    ``docker run -ti -p 5000:5000 gsiupm/senpy-python2.7 --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 gsiupm/senpy --host 0.0.0.0 --default-plugins -f /plugins``
--- a/docs/plugins.rst
+++ b/docs/plugins.rst
@ -2,6 +2,8 @@ Developing new plugins
 ----------------------
 This document describes how to develop a new analysis plugin. For an example of conversion plugins, see :doc:`conversion`.

+There is also a tutorial for developing new plugins with slides `here <https://lab.cluster.gsi.dit.upm.es/senpy/senpy-tutorial>`__ 
+
 Each plugin represents a different analysis process.There are two types of files that are needed by senpy for loading a plugin:

 - Definition file, has the ".senpy" extension.
--- a/docs/senpy.rst
+++ b/docs/senpy.rst
@ -1,35 +1,18 @@
 What is Senpy?
 --------------

-Senpy is an open source reference implementation of a linked data model for sentiment and emotion analysis services based on the vocabularies NIF, Marl and Onyx. 
+Senpy is a framework to build semantic sentiment and emotion analysis services. Using Senpy you can easy develop and publish your own analysis algorithms.

-The overall goal of the reference implementation Senpy is easing the adoption of the proposed linked data model for sentiment and emotion analysis services, so that services from different providers become interoperable. With this aim, the design of the reference implementation has focused on its extensibility and reusability. 
+If you use Senpy, please cite `Senpy: A Pragmatic Linked Sentiment Analysis Framework <http://gsi.dit.upm.es/index.php/es/investigacion/publicaciones?view=publication&task=show&id=417>`__ (`BibTex <http://gsi.dit.upm.es/index.php/es/investigacion/publicaciones?controller=publications&task=export&format=bibtex&id=417>`__):

-A modular approach allows organizations to replace individual components with custom ones developed in-house. Furthermore, organizations can benefit from reusing prepackages modules that provide advanced functionalities, such as algorithms for sentiment and emotion analysis, linked data publication or emotion and sentiment mapping between different providers.
+.. code-block:: text

-Specifications
-==============
+	Sánchez-Rada, J. F., Iglesias, C. A., Corcuera, I., & Araque, Ó. (2016, October).
+	Senpy: A Pragmatic Linked Sentiment Analysis Framework.
+	In Data Science and Advanced Analytics (DSAA),
+	2016 IEEE International Conference on (pp. 735-742). IEEE.

-The model used in Senpy is based on the following specifications:
+.. toctree::
+   	specifications
+   	architecture

-* Marl, a vocabulary designed to annotate and describe subjetive opinions expressed on the web or in information systems.
-* Onyx, which is built one the same principles as Marl to annotate and describe emotions, and provides interoperability with Emotion Markup Language.
-* NIF 2.0, which defines a semantic format and APO for improving interoperability among natural language processing services
-
-Architecture
-============
-
-The main component of a sentiment analysis service is the algorithm itself. However, for the algorithm to work, it needs to get the appropriate parameters from the user, format the results according to the defined API, interact with the user whn errors occur or more information is needed, etc.
-
-Senpy proposes a modular and dynamic architecture that allows:
-
-* Implementing different algorithms in a extensible way, yet offering a common interface.
-* Offering common services that facilitate development, so developers can focus on implementing new and better algorithms.
-
-The framework consists of two main modules: Senpy core, which is the building block of the service, and Senpy plugins, which consist of the analysis algorithm. The next figure depicts a simplified version of the processes involved in an analysis with the Senpy framework.
-
-.. image:: senpy-architecture.png
-  :height: 400px
-  :width: 800px
-  :scale: 100 %
-  :align: center
--- a/docs/specifications.rst
+++ b/docs/specifications.rst
@ -0,0 +1,8 @@
+Specifications
+==============
+
+The model used in Senpy is based on the following specifications:
+
+* Marl, a vocabulary designed to annotate and describe subjetive opinions expressed on the web or in information systems.
+* Onyx, which is built one the same principles as Marl to annotate and describe emotions, and provides interoperability with Emotion Markup Language.
+* NIF 2.0, which defines a semantic format and APO for improving interoperability among natural language processing services