MF-199 - Create documentation skeleton (#218)

* Copy basic docs contents to the main repo

Signed-off-by: Dejan Mijic <dejan@mainflux.com>

* Include licensing and contributing info to docs

Signed-off-by: Dejan Mijic <dejan@mainflux.com>

* Create documentation skeleton

Signed-off-by: Dejan Mijic <dejan@mainflux.com>

.github/CONTRIBUTING.md

@@ -38,58 +38,51 @@ maintainers might not want to merge into the project.
 Please adhere to the coding conventions used throughout the project. If in doubt, consult the
 [Effective Go](https://golang.org/doc/effective_go.html) style guide.
 
-Adhering to the following process is the best way to get your work included in the project:
+To start contributing to the project, [fork](https://help.github.com/articles/fork-a-repo/) it,
+clone your fork repository, and configure the remotes:
 
-1. [Fork](https://help.github.com/articles/fork-a-repo/) the project, clone your fork, and configure
-   the remotes:
+```
+git clone https://github.com/<your-username>/mainflux.git
+cd mainflux
+git remote add upstream https://github.com/mainflux/mainflux.git
+```
 
-   ```bash
-   # Clone your fork of the repo into the current directory
-   git clone https://github.com/<your-username>/mainflux.git
+If you cloned a while ago, get the latest changes from upstream:
 
-   # Navigate to the newly cloned directory
-   cd mainflux
+```
+git checkout master
+git pull --rebase upstream master
+```
 
-   # Assign the original repo to a remote called "upstream"
-   git remote add upstream https://github.com/mainflux/mainflux.git
-   ```
+Create a new topic branch from `master` using the naming convention `MF-[issue-number]`
+to help us keep track of your contribution scope:
 
-2. If you cloned a while ago, get the latest changes from upstream:
+```
+git checkout -b MF-[issue-number]
+```
 
-   ```bash
-   git checkout master
-   git pull --rebase upstream master
-   ```
+Commit your changes in logical chunks. When you are ready to commit, make sure
+to write a Good Commit Message™. Consult the [Erlang's contributing guide](https://github.com/erlang/otp/wiki/Writing-good-commit-messages)
+if you're not sure what constitutes a Good Commit Message™. Use [interactive rebase](https://help.github.com/articles/about-git-rebase)
+to group your commits into logical units of working before making them public.
 
-3. Create a new topic branch from `master` using the naming convention `MF-[issue-number]` to
-   help us keep track of your contribution scope:
+Note that every commit you make must be signed. By signing off your work you indicate that you
+are accepting the [Developer Certificate of Origin](https://developercertificate.org/).
 
-   ```bash
-   git checkout -b MF-[issue-number]
-   ```
+Use your real name (sorry, no pseudonyms or anonymous contributions). If you set your `user.name`
+and `user.email` git configs, you can sign your commit automatically with `git commit -s`.
 
-4. Commit your changes in logical chunks. When you are ready to commit, make sure to write a Good
-   Commit Message™. Consult the [Erlang's contributing guide](https://github.com/erlang/otp/wiki/Writing-good-commit-messages)
-   if you're not sure what constitutes a Good Commit Message™. Use [interactive rebase](https://help.github.com/articles/about-git-rebase)
-   to group your commits into logical units of working before making them public.
+Locally merge (or rebase) the upstream development branch into your topic branch:
 
-   Note that every commit you make must be signed. By signing off your work you indicate that you
-   are accepting the [Developer Certificate of Origin](https://developercertificate.org/).
+```
+git pull --rebase upstream master
+```
 
-   Use your real name (sorry, no pseudonyms or anonymous contributions). If you set your `user.name`
-   and `user.email` git configs, you can sign your commit automatically with `git commit -s`.
+Push your topic branch up to your fork:
 
-5. Locally merge (or rebase) the upstream development branch into your topic branch:
+```
+git push origin MF-[issue-number]
+```
 
-   ```bash
-   git pull --rebase upstream master
-   ```
-
-6. Push your topic branch up to your fork:
-
-   ```bash
-   git push origin MF-[issue-number]
-   ```
-
-7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title
-   and detailed description.
+[Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title
+and detailed description.

.gitignore

@@ -1,2 +1,4 @@
 build
 *.pb.go
+
+site/

LICENSE

@@ -176,7 +176,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2015 Mainflux
+   Copyright 2015-2018 Mainflux
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -35,7 +35,7 @@ Once everything is installed, execute the following commands from project root:
 
 ```bash
 cd docker/
-docker-compose up -d
+docker-compose up -f docker/docker-compose.yml -d
 ```
 
 ## Contributing
@@ -52,7 +52,7 @@ Thank you for your interest in Mainflux and wish to contribute!
 - [Gitter][gitter]
 - [Twitter][twitter]
 
-[banner]: https://github.com/mainflux/doc/blob/master/docs/img/gopherBanner.jpg
+[banner]: https://github.com/mainflux/mainflux/blob/master/docs/img/gopherBanner.jpg
 [ci-badge]: https://semaphoreci.com/api/v1/mainflux/mainflux/branches/master/badge.svg
 [ci-url]: https://semaphoreci.com/mainflux/mainflux
 [docs]: http://mainflux.readthedocs.io

docs/CONTRIBUTING.md

@@ -0,0 +1 @@
+../.github/CONTRIBUTING.md

docs/LICENSE.txt

@@ -0,0 +1 @@
+../LICENSE

docs/architecture.md

@@ -0,0 +1,47 @@
+## Components
+
+Mainflux IoT platform is comprised of the following services:
+
+| Service                                                                   | Description                                                             |
+|:--------------------------------------------------------------------------|:------------------------------------------------------------------------|
+| [manager](https://github.com/mainflux/mainflux/tree/master/manager)       | Manages platform entities, and auth concerns                            |
+| [http-adapter](https://github.com/mainflux/mainflux/tree/master/http)     | Provides an HTTP interface for accessing communication channels         |
+| [normalizer](https://github.com/mainflux/mainflux/tree/master/normalizer) | Normalizes SenML messages and generates the "processed" messages stream |
+
+> The following diagram is an (obsolete) overview of platform architecture
+
+![arch](img/architecture.jpg)
+
+## Domain model
+
+The platform is built around 3 main entities: **users**, **clients** and **channels**.
+
+`User` represents the real (human) user of the system. It is represented via its
+e-mail and password, which he uses as platform access credentials in order to obtain
+an access token. Once logged into the system, user can manage his resources in
+CRUD fashion (i.e. channels and clients), and define access control policies
+between them.
+
+`Device` is used to represent any device that connects to Mainflux. It is a
+generic model that describes any client device of the system.
+
+`Application` is very similar to the `Device` and is represented by the same
+`Client` structure (just with different `type` info). Application represents
+an end-user application that communicates with devices through Mainflux, and
+can be running somewhere in the cloud, locally on the PC or on the mobile phone.
+Usually it acquires data from sensor measurement and displays it on various
+dashboards.
+
+`Channel` represents a communication channel. It serves as message topic that
+can be consumed by all of the clients connected to it.
+
+## Messaging
+
+Mainflux uses [NATS](https://nats.io) as its messaging backbone, due to its
+lightweight and performant nature. You can treat its *subjects* as physical
+representation of Mainflux channels, where subject name is constructed using
+channel unique identifier.
+
+In general, there is no constrained put on content that is being exchanged
+through channels. However, in order to be post-processed and normalized,
+messages should be formatted using [SenML](https://tools.ietf.org/html/draft-ietf-core-senml-08).

docs/getting-started.md

@@ -0,0 +1,71 @@
+## Prerequisites
+
+Before proceeding, install the following prerequisites:
+
+- [Docker](https://docs.docker.com/install/)
+- [Docker compose](https://docs.docker.com/compose/install/)
+- [jsonpp](https://jmhodges.github.io/jsonpp/) (optional)
+
+Once everything is installed, execute the following commands from project root:
+
+```bash
+cd docker/
+docker-compose up -f docker/docker-compose.yml -d
+```
+
+## User management
+
+### Account creation
+
+TBD
+
+### Obtaining an authorization key
+
+TBD
+
+## System provisioning
+
+Before proceeding, make sure that you have created a new account, and obtained
+an authorization key.
+
+### Provisioning devices
+
+TBD
+
+### Provisioning applications
+
+TBD
+
+### Retrieving provisioned clients
+
+TBD
+
+### Removing clients
+
+TBD
+
+### Provisioning channels
+
+TBD
+
+### Retrieving provisioned channels
+
+TBD
+
+### Removing channels
+
+TBD
+
+## Access control
+
+TODO: describe how to connect & disconnect clients to/from channels
+
+## Sending messages
+
+Once a channel is provisioned and client is connected to it, it can start to
+publish messages on the channel. The following sections will provide an example
+of message publishing for each of the supported protocols.
+
+### HTTP
+
+TBD

docs/index.md

@@ -0,0 +1,17 @@
+## What is Mainflux?
+
+Mainflux is modern, scalable, secure open source and patent-free IoT cloud platform written in Go.
+
+It accepts user, device, and application connections over various network protocols (i.e. HTTP,
+MQTT, WebSocket, CoAP), thus making a seamless bridge between them. It is used as the IoT middleware
+for building complex IoT solutions.
+
+![banner](img/gopherBanner.jpg)
+
+## Features
+
+- Protocol bridging (i.e. HTTP, MQTT, WebSocket, CoAP)
+- Device management and provisioning
+- Fine-grained access control
+- Platform logging and instrumentation support
+- Container-based deployment using Docker

mkdocs.yml

@@ -0,0 +1,43 @@
+# Copyright (c) 2016 Martin Donath <martin.donath@squidfunk.com>
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+copyright: Copyright (c) 2015-2018 Mainflux
+repo_url: https://github.com/mainflux/mainflux
+site_description: Mainflux IoT System
+site_name: Mainflux
+theme: readthedocs
+
+extra:
+  logo: docs/img/logo.png
+  author:
+    github: mainflux/mainflux
+    twitter: mainflux
+
+markdown_extensions:
+  - admonition
+  - toc:
+      permalink: '#'
+
+pages:
+- Overview:
+    - About: index.md
+    - Contributing: CONTRIBUTING.md
+    - License: LICENSE.txt
+- Architecture: architecture.md
+- Getting started: getting-started.md