Split Documentation

This is a major cleanup. Instead of having broken links between C++ and
QML we now have 3 projects so that name-clashes do not occur any more.
It has the downside that Enginio shows up as three projects in Assistant
now, but at least all the docs are there and links work.

Change-Id: I30a79b9dc586117e19489c6ff5962fc1ef87f89f
Reviewed-by: Jędrzej Nowacki <jedrzej.nowacki@digia.com>

3 files changed, 340 insertions, 0 deletions

diff --git a/doc/enginio_overview.qdoc b/doc/enginio_overview.qdoc
new file mode 100644
index 0000000..55d9ba7
--- /dev/null
+++ b/doc/enginio_overview.qdoc
@@ -0,0 +1,311 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of Enginio.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page index.html
+\contentspage {Enginio Manual}{Contents}
+\indexpage Enginio Manual
+\startpage Enginio Manual
+\nextpage Enginio Installation and Prerequisites
+
+\title Enginio Manual
+
+Enginio is a Backend-as-a-Service solution to ease backend development for any connected and data-driven application.
+
+\section1 Tutorials
+
+To get started quickly, follow the mini-tutorial using Qt Quick or C++.
+\list
+\li \l {Enginio Installation and Prerequisites}
+\li \l {Getting Started with Enginio using Qt Quick}
+\li \l {Getting Started with Enginio using C++}
+\endlist
+
+\section1 Reference documentation and examples:
+\list
+\li \l {Enginio C++ Classes and Examples}
+\li \l {Enginio QML Types and Examples}
+\endlist
+
+\section1 Overview
+
+When using Enginio (with Qt Quick or C++), the API is following a general pattern that will be helpful to understand.
+This section gives a short, high-level overview of the concepts used throughout the library.
+
+The Qt library is a client-side library to communicate with the server at \l {http://engin.io}.
+Several backends can exist for each account on the server.
+For all communication with the server, the backend is determined by its ID.
+When shipping an application built with Enginio, the backend id will be the same for all users of that application.
+
+\section2 Objects
+
+Enginio provides several types of objects: "custom objects", "users", "user groups", "files" and more.
+All communication with the backend uses JSON. When writing QML, JSON can simply be written inline.
+On the C++ side, \l QJsonObject and \l QJsonValue are used.
+
+Each object in the database has an \c id, \c objectType, \c createdAt and \c updatedAt property that are reserved and always exist.
+For example, a custom object with no additional properties (in JSON) might look like this:
+\code
+{
+    "id": "51cdbc08989e975ec300772a",
+    "objectType": "objects.todos",
+    "createdAt": "2013-06-28T16:38:32.369Z",
+    "updatedAt": "2013-06-28T16:38:32.725Z"
+}
+\endcode
+With this basis, the objects can be augmented with user defined properties that contain the actual application data and can
+even contain other objects.
+For a more detailed description see the \l{http://engin.io/documentation/overview/objects}{Enginio Object documentation}.
+
+\section2 Operations
+
+To operate on objects of any type, the basic operations are:
+\list
+\li create: create a new object
+\li query:  list objects
+\li update: change an object
+\li remove: delete an object
+\endlist
+
+For a detailed description of the operations see the functions
+in the \l {EnginioClient}{EnginioClient Class} in C++ or \l {Enginio1::EnginioClient}{EnginioClient type} in QML.
+
+\note User management and access control lists are conveniently done by the same functions.
+
+\section2 File Management
+
+For file management, the operations are slightly different.
+Files are always attached to objects and can only be referenced through them.
+The Qt library provides convenient functions to upload and download files.
+
+The entire Enginio documentation including backend and client is available here: \l{http://engin.io/documentation/}{Enginio Documentation}
+*/
+
+/*!
+\page enginio-getting-started
+\indexpage Enginio Manual
+\nextpage Getting Started with Enginio using Qt Quick
+\previouspage Enginio Manual
+
+\title Enginio Installation and Prerequisites
+
+This guide shows how to use the Enginio Qt library in a Qt application
+(both Qt C++ and QML cases are covered).
+This guide can be also applied when integrating Enginio with existing Qt projects.
+
+\section1 Prerequisites
+
+You can use Enginio with an existing installation of Qt 5.2 or later, or get Qt packages containing Engino (starting with Qt 5.2).
+
+\list
+  \li  Development environment (Linux, Windows or Mac OS X) and compiler toolchain.
+  \li  Qt framework, 5.2 or newer
+  \li  OpenSSL to enable SSL support in Qt.
+       Install the OpenSSL binaries into your system and Qt will automatically pick them up.
+
+       \list
+         \li Mac OS X: the OpenSSL library should be preinstalled in the system
+         \li Linux: Most distributions have a preinstalled OpenSSL library. If yours doesn't, install libssl via your distribution's package manager
+         \li Windows: Install Win32 OpenSSL (light version is enough, copy DLLs to windows system directory when asked)
+       \endlist
+
+    \li Perl 5.10 or newer to enable Qt5 module compilation
+    \list
+        \li Mac OS X: Perl should exist as preinstalled in the system
+        \li Linux: Perl should exist as preinstalled in the system
+        \li Windows: Install some Perl distribution
+    \endlist
+\endlist
+
+\section1 Install Enginio Qt library
+
+\list
+  \li  Download the latest library release for your platform
+  \li  Execute downloaded binary installer and follow instructions
+\endlist
+*/
+
+/*!
+\page enginio-qml
+\indexpage Enginio Manual
+\nextpage Getting Started with Enginio using C++
+\previouspage Enginio Installation and Prerequisites
+
+\title Getting Started with Enginio using Qt Quick
+\brief Introduction to using Enginio using Qt Quick
+
+\section1 Setup a Qt Quick 2 application project
+
+Create a new Qt Quick 2 Application.
+
+You can use Qt Creator to get started with a template.
+(File ⇒ New File or Project ⇒ Applications ⇒ Qt Quick 2 Application)
+
+\section1 Initialize Enginio Client
+
+To use Enginio's QML API, you have to import the library.
+\code
+import Enginio 1.0
+\endcode
+
+Initialize the \l{Enginio1::EnginioClient}{enginio client} with the \l{EnginioClient::backendId}{backend id} value, which can be copied from the Dashboard.
+
+Go to Dashboard ⇒ Your Backend home-view ⇒ See ’Keys box’ ⇒ Copy backend id value.
+
+\code
+EnginioClient {
+    id: enginio
+    backendId: "YOUR_OWN_BACKEND_ID"
+}
+\endcode
+
+\section1 Store your first Object
+
+Now you can store an Object with Enginio. First, create an object in JSON format and fill it with data as needed.
+Then call create on the client with the JSON object as a parameter.
+
+\code
+Component.onCompleted: {
+    var city = {
+        objectType: "objects.city",
+        name: "Helsinki",
+        population: 606000
+    };
+    enginio.create(city);
+}
+\endcode
+
+Now you can \l{Checking stored objects in the Dashboard}{check the Enginio dashboard} for the newly created object.
+*/
+
+
+/*!
+\page enginio-cpp
+\indexpage Enginio Manual
+\nextpage Checking stored objects in the Dashboard
+\previouspage Getting Started with Enginio using Qt Quick
+
+\title Getting Started with Enginio using C++
+\brief Introduction to using Enginio using C++
+
+\section1 Setup Qt application project
+
+You need to link to Enginio. For qmake-based projects simply add
+\code
+QT += enginio
+\endcode
+to your \c .pro file.
+
+\section1 Initialize Enginio Client
+
+To use the Enginio Qt library in your code, you have to include relevant library headers.
+\code
+ #include <Enginio/Enginio>
+\endcode
+Before making any calls to the Enginio API, the \l EnginioClient needs to be instantiated.
+They can be copied from the Dashboard.
+Go to the \l{https://dashboard.engin.io/}{Enginio Dashboard} and select a backend.
+Copy the backend id value.
+
+\code
+QByteArray backendId("YOUR_OWN_BACKEND_ID");
+EnginioClient *client = new EnginioClient;
+client->setBackendId(backendId);
+\endcode
+For testing purposes, it is easiest to hardcode the backend id directly into application code. However, this might not be always the best choice, and sometimes it might be beneficial to put the backend configuration in a separate configuration file.
+\section1 Store your first Object
+
+Create an object in JSON format and fill in the data:
+\code
+    QJsonObject city;
+    city.insert("objectType", QString("objects.city")); // an object type is required for all objects in Enginio
+    city.insert("name", QString("Oslo")); // other properties can be chosen freely
+    city.insert("population", 624000);
+\endcode
+
+Create the object in the Enginio database by calling \l{EnginioClient::create()}:
+\code
+    client->create(city);
+    connect(client, SIGNAL(finished(EnginioReply*)), this, SLOT(uploadFinished(EnginioReply*)));
+\endcode
+Note that the \l{EnginioClient::create()}{create()} method performs the actual asynchronous network communication.
+You need to wait for its completion by connecting to the \l{EnginioClient::finished()}{finished} and \l{EnginioClient::error()}{error} signals.
+
+Now you can \l{Checking stored objects in the Dashboard}{check the Enginio dashboard} for the newly created object.
+*/
+
+
+/*!
+\page enginio-dashboard.html
+\title Checking Stored Objects in the Dashboard
+\indexpage Enginio Manual
+\previouspage Getting Started with Enginio using C++
+
+When you have successfully stored objects with Qt C++ or QML code, go to your \l{https://dashboard.engin.io/}{Enginio Dashboard}
+and check the status there.
+
+\list
+\li Select the ’Objects’ view from the top navigation bar.
+\li Make sure that objects.city is selected in the type drop-down.
+\li The list should now show a row for the object which was just uploaded.
+\endlist
+\image object_browser_first_city_object.png
+
+For more information on how to interact with Enginio, read the \l EnginioClient documentation.
+To get convenient access to objects stored in Enginio, consider using \l EnginioModel.
+*/
+
+/*!
+\page tutorials.html
+\title Enginio Tutorials
+\indexpage Enginio Manual
+
+\list
+\li \l {Enginio Installation and Prerequisites}
+\li \l {Getting Started with Enginio using Qt Quick}
+\li \l {Getting Started with Enginio using C++}
+\endlist
+*/
+
+/*!
+\page enginio-classes.html
+\title Enginio C++ Classes
+\indexpage Enginio Manual
+
+Enginio provides these \b{C++ classes}:
+\generatelist {classesbymodule enginio-qt}
+*/
+
+/*!
+\page enginio-qml-types.html
+\title Enginio QML Types
+\indexpage Enginio Manual
+
+Enginio provides these \b{QML types}:
+\annotatedlist engino-qml
+*/
+
diff --git a/doc/images/object_browser_first_city_object.png b/doc/images/object_browser_first_city_object.png
new file mode 100644
index 0000000..6024be3
--- /dev/null
+++ b/doc/images/object_browser_first_city_object.png
diff --git a/doc/qtenginio.qdocconf b/doc/qtenginio.qdocconf
new file mode 100644
index 0000000..58bef9a
--- /dev/null
+++ b/doc/qtenginio.qdocconf
@@ -0,0 +1,29 @@
+include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+
+project = QtEnginio
+description = Enginio Client Library
+url = http://engin.io
+
+sourcedirs += .
+headerdirs += .
+
+imagedirs += images
+
+depends += qtcore qtgui qtwidgets qtnetwork qtdoc qtenginiocpp qtenginioqml
+
+qhp.projects            = Enginio
+
+qhp.Enginio.file                = qtenginio.qhp
+qhp.Enginio.namespace           = io.engin.100
+qhp.Enginio.virtualFolder       = enginio
+qhp.Enginio.indexTitle          = Enginio Manual
+
+qhp.Enginio.filterAttributes    = enginio 1.0.0
+qhp.Enginio.customFilters.Qt.name = Enginio 1.0.0
+qhp.Enginio.customFilters.Qt.filterAttributes = enginio 1.0.0
+
+qhp.Enginio.subprojects = manual
+qhp.Enginio.subprojects.manual.title = Manual
+qhp.Enginio.subprojects.manual.indexTitle = Enginio Manual
+qhp.Enginio.subprojects.manual.selectors = fake:page
+