Clearer docs

docs/architecture.rst

@@ -1,15 +0,0 @@
-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
-  :width: 100%
-  :align: center

docs/index.rst

@@ -13,21 +13,16 @@ Welcome to Senpy's documentation!
 
 
 
-With Senpy, you can easily turn your sentiment or emotion analysis algorithm into a full blown semantic service.
+Senpy is a framework for sentiment and emotion analysis services.
-Sharing your sentiment analysis with the world has never been easier.
+Services built with senpy are interchangeable and easy to use because they share a common :doc:`apischema`.
-Senpy provides:
+It also simplifies service development.
-
-* Parameter validation, error handling
-* Formatting: JSON-LD, Turtle/n-triples input and output, or simple text input
-* Linked Data. Results are semantically annotated, using a series of well established vocabularies, and sane default URIs.
-* A web UI where users can explore your service and test different settings
-* A client to interact with any senpy service
-* A command line tool
-
 
+.. image:: senpy-architecture.png
+  :width: 100%
+  :align: center
 
 .. toctree::
-   :caption: Learn more about senpy
+   :caption: Learn more about senpy:
    :maxdepth: 2
 
    senpy

docs/installation.rst

@@ -1,6 +1,16 @@
 Installation
 ------------
-The stable version can be installed in three ways.
+The stable version can be used in two ways: as a system/user library through pip, or as a docker image.
+
+The docker image is the recommended way because it is self-contained and isolated from the system, which means:
+
+  * Downloading and using it is just one command
+  * All dependencies are included
+  * It is OS-independent (MacOS, Windows, GNU/Linux)
+  * Several versions may coexist in the same machine without additional virtual environments
+
+Additionally, you may create your own docker image with your custom plugins, ready to be used by others.
+
 
 Through PIP
 ***********
@@ -34,15 +44,6 @@ To add custom plugins, use a docker volume:
 
    docker run -ti -p 5000:5000 -v <PATH OF PLUGINS>:/plugins gsiupm/senpy --host 0.0.0.0 --default-plugins -f /plugins
  
-Alias
-.....
-
-If you are using the docker approach regularly, it is advisable to use a script or an alias to simplify your executions:
-
-.. code:: bash
-
-   alias senpy='docker run --rm -ti -p 5000:5000 -v $PWD:/senpy-plugins gsiupm/senpy --default-plugins'
- 
 
 Python 2
 ........
@@ -54,3 +55,18 @@ 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
 
 
+Alias
+.....
+
+If you are using the docker approach regularly, it is advisable to use a script or an alias to simplify your executions:
+
+.. code:: bash
+
+   alias senpy='docker run --rm -ti -p 5000:5000 -v $PWD:/senpy-plugins gsiupm/senpy --default-plugins'
+
+
+Now, you may run senpy from any folder in your computer like so:
+
+.. code:: bash
+
+   senpy --version

docs/plugins.rst

@@ -139,6 +139,28 @@ Now, in a file named ``helloworld.py``:
                   entry.sentiments.append(sentiment)
                   yield entry
 
+Docker image
+============
+
+Add the following dockerfile to your project to generate a docker image with your plugin:
+
+.. code:: dockerfile
+
+   FROM gsiupm/senpy:0.8.8
+
+This will copy your source folder to the image, and install all dependencies.
+Now, to build an image:
+
+.. code:: shell
+
+   docker build . -t gsiupm/exampleplugin
+
+And you can run it with:
+
+.. code:: shell
+
+   docker run -p 5000:5000 gsiupm/exampleplugin
+
 
 F.A.Q.
 ======

docs/senpy.rst

@@ -1,6 +1,26 @@
 What is Senpy?
 --------------
 
+Web services can get really complex: data validation, user interaction, formatting, logging., etc. 
+The figure below summarizes the typical features in an analysis service.
+Senpy implements all the common blocks, so developers can focus on what really matters: great analysis algorithms that solve real problems.
+
+.. image:: senpy-framework.png
+  :width: 60%
+  :align: center
+
+
+Senpy for end users
+===================
+
+All services built using senpy share a common interface.
+This allows users to use them (almost) interchangeably.
+Senpy comes with a :ref:`built-in client`.
+
+
+Senpy for service developers
+============================
+
 Senpy is a framework that turns your sentiment or emotion analysis algorithm into a full blown semantic service.
 Senpy takes care of:
 
@@ -12,21 +32,20 @@ Senpy takes care of:
 
 Sharing your sentiment analysis with the world has never been easier!
 
-Senpy for service developers
-============================
-
 Check out the :doc:`plugins` if you have developed an analysis algorithm (e.g. sentiment analysis) and you want to publish it as a service.
 
-Senpy for end users
+Architecture
-===================
+============
 
-All services built using senpy share a common interface.
+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.
-This allows users to use them (almost) interchangeably.
-Senpy comes with a :ref:`built-in client`.
 
+Senpy proposes a modular and dynamic architecture that allows:
 
-.. toctree::
+* Implementing different algorithms in a extensible way, yet offering a common interface.
-    :caption: Interested? Check out senpy's:
+* Offering common services that facilitate development, so developers can focus on implementing new and better algorithms.
 
-    architecture
+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
+  :width: 100%
+  :align: center

docs/server.rst

@@ -1,9 +1,9 @@
-Senpy server
+Server
-============
+======
 
 The senpy server is launched via the `senpy` command:
 
-::
+.. code:: text
 
     usage: senpy [-h] [--level logging_level] [--debug] [--default-plugins]
                 [--host HOST] [--port PORT] [--plugins-folder PLUGINS_FOLDER]
@@ -25,13 +25,29 @@ The senpy server is launched via the `senpy` command:
 
 
 When launched, the server will recursively look for plugins in the specified plugins folder (the current working directory by default).
+For every plugin found, it will download its dependencies, and try to activate it.
 The default server includes a playground and an endpoint with all plugins found.
 
+Let's run senpy with the default plugins:
+
+.. code:: bash
+
+    senpy -f . --default-plugins
+
+Now go to `http://localhost:5000 <http://localhost:5000>`_, you should be greeted by the senpy playground:
+
+.. image:: senpy-playground.png
+   :width: 100%
+   :alt: Playground
+
+The playground is a user-friendly way to test your plugins, but you can always use the service directly:  `http://localhost:5000/api?input=hello <http://localhost:5000/api?input=hello>`_.
+
+
 By default, senpy will listen only on the `127.0.0.1` address.
 That means you can only access the API from your (or localhost).
-You can listen on a different address using the `--host` flag.
+You can listen on a different address using the `--host` flag (e.g., 0.0.0.0).
 The default port is 5000.
-You can change bothbut you can change it using the `--port` flag. 
+You can change it with the `--port` flag. 
 
 For instance, to accept connections on port 6000 on any interface:
 
@@ -40,9 +56,3 @@ For instance, to accept connections on port 6000 on any interface:
     senpy --host 0.0.0.0 --port 6000
 
 For more options, see the `--help` page.
-
-
-Customizing senpy
-=================
-Senpy is built on top of Flask, the web framework.
-Although it is not the recommendad way, you may customize senpy by extending the extensions, blueprints and modules provided in the senpy module.

docs/usage.rst

@@ -2,13 +2,14 @@ Usage
 -----
 
 First of all, you need to install the package.
-See :doc:`installation` for installation instructions.
+See :doc:`installation` for instructions.
 Once installed, the `senpy` command should be available. 
 
 .. toctree::
+   :maxdepth: 1
 
-   SenpyClientUse
    server
+   SenpyClientUse
    commandline