Merge pull request #45 from giovannicuriel/update-documentation

Update documentation

source/architecture.rst

@@ -36,24 +36,28 @@ directly using the REST APIs provided by the API Gateway. Data processing flows
 might be also configured - these entities can perform a variety of actions,
 such as generate notifications when a particular device attribute reaches a
 certain threshold or save all data generated by a device onto an external
-database. As devices start sending their readings to dojot, the user might want
-to receive these readings via notifications generated by subscriptions,
-consolidate all data into virtual devices, gather all data from historical
-database, and so on. These features can be used through REST APIs - these are
-the basic building blocks that any application based on dojot should use. dojot
-GUI provides an easy way to perform management operations for all entities
-related to the platform (users, devices, templates and flows) and can also be
-used to check if everything is working fine.
-
-The user contexts are isolated and there is no data sharing, the access
+database. As devices start sending their readings to dojot, a user can:
+
+- receive these readings via notifications generated by subscriptions;
+- consolidate all data into virtual devices;
+- gather all data from historical database, and so on.
+
+These features can be used through REST APIs - these are the basic building
+blocks that any application based on dojot should use. dojot GUI provides an
+easy way to perform management operations for all entities related to the
+platform (users, devices, templates and flows) and can also be used to check if
+everything is working fine.
+
+The user context are isolated and there is no data sharing, the access
 credentials are validated by the authorization service for each and every
-operation (API Request). Once devices are configured, the IoT Agent is capable
-of mapping the data received from devices, encapsulated on MQTT for example,
-and send them to the context broker for internal distribution, reaching, for
-instance, the history service so it can persist the data on a database. If
-certain conditions are matched when rules are being processed, a new event is
-generated and sent to the broker service to be redistributed to the interested
-services.
+operation (API Request). Therefore, a user belonging to a particular context
+(tenant) cannot reach any data (including devices, templates, flows or any
+other data related to these resources) from other ones.
+
+Once devices are configured, the IoT Agent is capable of mapping the data
+received from devices, encapsulated on MQTT for example, and send them to the
+message broker for internal distribution. This way, the data reaches the
+history service, for instance, so it can persist the data on a database.
 
 For more information about what's going on with dojot, you should take a look
 at `dojot GitHub repository <https://github.com/dojot>`_. There you'll find all
@@ -62,8 +66,8 @@ components used in dojot.
 Each one of the components that are part of the architecture are briefly
 described on the sub-sections below.
 
-Kafka + data-broker + NGSI
-***********************************
+Kafka + DataBroker
+******************
 
 Apache Kafka is a distributed messaging platform that can be used by
 applications which need to stream data or consume/produce data pipelines. In
@@ -74,17 +78,14 @@ isolation, simplicity, and so on).
 In Kafka, a specialized topics structure is used to insure isolation between
 different users and applications data, enabling a multi-tenant infrastructure.
 
-The flow-broker service makes use of an in-memory database for efficiency. It
+The DataBroker service makes use of an in-memory database for efficiency. It
 adds context to Apache Kafka, making it possible that internal or even external
-services are able to subscribe or query data based on context. Flow-broker is
+services are able to subscribe or query data based on context. DataBroker is
 also a distributed service to avoid it being a single point of failure or even
 a bottleneck for the architecture.
 
-To keep a certain level of compatibility with NGSI-compatible components, it is
-possible to build an element that offers a NGSI interface for such components.
-
 DeviceManager
-**************
+*************
 
 DeviceManager is a core entity which is responsible for keeping device and
 templates data models. It is also responsible for publishing any updates to all
@@ -144,8 +145,8 @@ to be used.
 Logging and Auditing Service
 ****************************
 
-All the services that are part of the *dojot* platform can generate usage metrics
-of its resources that can be used by a logging and auditing service,
+All the services that are part of the *dojot* platform can generate usage
+metrics of its resources that can be used by a logging and auditing service,
 which process this registers and summarize then based on users and
 applications.
 
@@ -204,6 +205,8 @@ Alarm Management
 This component is responsible for handling alarms generated by dojot's internal
 components, such as IoT agents, Device Manager, and so on.
 
+This component is also scheduled for development.
+
 Image manager
 *************
 

source/components-and-apis.rst

@@ -10,31 +10,31 @@ Components
   :header-rows: 1
 
   * - Component
-    - GitHub repository
+    - Repository / Main site
     - Documentation
-  * - mongodb
-    -
-    - `mongodb documentation`_
+  * - MongoDB
+    - `MongoDB official site`_
+    - `MongoDB documentation`_
   * - postgres
-    -
-    - `postgres documentation`_
-  * - Kong API gateway
-    -
+    - `PostgreSQL official site`_
+    - `PostgreSQL documentation`_
+  * - Kong API gateway (Community Edition)
+    - `Kong official site`_
     - `Kong documentation`_
   * - redis
-    -
+    - `Redis official site`_
     - `Redis documentation`_
   * - zookeeper
-    -
+    - `Zookeeper official site`_
     - `Zookeeper documentation`_
   * - Kafka
-    -
+    - `Kafka official site`_
     - `Kafka documentation`_
   * - auth
     - `GitHub - auth`_
     - `readthedocs - auth`_
   * - History
-    - `GitHub - history-ws`_
+    - `GitHub - history`_
     -
   * - DeviceManager
     - `GitHub - DeviceManager`_
@@ -98,12 +98,8 @@ Exposed APIs
     - `GitHub - auth`_
   * - /history
     -  Device historical data
-    - `API - history-ws`_
-    - `GitHub - history-ws`_
-  * - /metric
-    -  Context broker
-    - `API - data-broker`_
-    - `GitHub - data-broker`_
+    - `API - history`_
+    - `GitHub - history`_
   * - /gui
     -  Graphical User Interface
     -
@@ -156,9 +152,6 @@ which component endpoint.
    * - STH
      - host:8666/
      - host:8000/history
-   * - Data-Broker
-     - host:1026/
-     - host:8000/metric
    * - GUI
      - host/
      - host:8000/gui
@@ -190,29 +183,39 @@ dojot.
    * - iotagent-mosca
      - Device data update (`Messages - iotagent-mosca`_)
      - ``device-data``
-
-.. _mongodb documentation: https://docs.mongodb.com/manual/
-.. _postgres documentation: https://www.postgresql.org/docs/
+   * - auth
+     - Tenants creation/removal (`Messages - auth`_)
+     - ``dojot.tenancy``
+
+.. _MongoDB documentation: https://docs.mongodb.com/manual/
+.. _MongoDB official site: https://www.mongodb.com/
+.. _PostgreSQL documentation: https://www.postgresql.org/docs/
+.. _PostgreSQL official site: https://www.postgresql.org
+.. _Kong official site: https://konghq.com/kong-community-edition/
 .. _Kong documentation: https://getkong.org/docs/
+.. _Redis official site: https://redis.io/
 .. _Redis documentation: https://redis.io/documentation
+.. _Zookeeper official site: https://zookeeper.apache.org/
 .. _Zookeeper documentation: https://zookeeper.apache.org/documentation.html
+.. _Kafka official site: https://kafka.apache.org/
 .. _Kafka documentation: http://kafka.apache.org/documentation/
 
 
 .. _GitHub - auth: https://github.com/dojot/auth
 .. _API - auth: https://dojot.github.io/auth/apiary_latest.html
 .. _readthedocs - auth: http://dojotdocs.readthedocs.io/projects/auth/en/latest/
+.. _Messages - auth: https://dojotdocs.readthedocs.io/projects/auth/en/latest/kafka-messages.html
 
-.. _GitHub - history-ws: https://github.com/dojot/history-ws
-.. _API - history-ws: https://dojot.github.io/history/apiary_latest.html
+.. _GitHub - history: https://github.com/dojot/history
+.. _API - history: https://dojot.github.io/history/apiary_latest.html
 
 
 .. _GitHub - DeviceManager: https://github.com/dojot/device-manager
 .. _API - DeviceManager: https://dojot.github.io/device-manager/apiary_latest.html
 .. _readthedocs - DeviceManager: http://dojotdocs.readthedocs.io/projects/DeviceManager/en/latest/
 .. _Messages - DeviceManager: http://dojotdocs.readthedocs.io/projects/DeviceManager/en/latest/kafka-messages.html
 
-.. _GitHub - image-manager: <https://github.com/dojot/image-manager>
+.. _GitHub - image-manager: https://github.com/dojot/image-manager
 .. _API - image-manager: https://dojot.github.io/image-manager/apiary_latest.html
 
 

source/concepts.rst

@@ -27,7 +27,7 @@ operations might become obscure and senseless.
 In the next section, there is an explanation of a few basic entities in dojot:
 devices, templates and flows. With these concepts in mind, we present a small
 tutorial to how to use them in dojot - it only covers API access. There a GUI
-oriented tutorial in :doc:`tutorials/using-web-interface` tutorial.
+oriented tutorial in :doc:`using-web-interface` tutorial.
 
 
 If you want more information on how dojot works internally, you should checkout

source/conf.py

@@ -179,3 +179,4 @@
 locale_dirs = ['locale/']  # path is example but recommended
 
 numfig = True
+numfig_secnum_depth = 1