Merge lp:~thomas-voss/location-service/fix-rtd-docs-next into lp:location-service

[Thomas Voß]

Introduce sections on the service CLI and API.

Introduce sections on the service CLI and API.

[Simon Fels (morphis)]

LGTM

review: Approve

=== added file 'doc/api.md'
--- doc/api.md	1970-01-01 00:00:00 +0000
+++ doc/api.md	2016-09-22 10:48:21 +0000
@@ -0,0 +1,33 @@
+# API
+
+Location service exposes a DBus API to interact with a service instance.
+We do not expose introspection for the API, yet. Instead, we provide a C++ client API that 
+abstracts away from the underlying IPC mechanism.
+
+A client application then uses the API to establish a session with a
+service, register observers to receive updates and to control the
+status of updates. The following snippet illustrates basic usage of the client API:
+
+```{cpp}
+auto service = location::connect_to_service(...);
+auto session = service->create_session_for_criteria(location::Criteria{});
+
+session->updates().position.changed().connect([this](const location::Update<location::Position>& pos)
+{
+  std::cout << pos << std::endl;
+});
+
+session->updates().heading.changed().connect([this](const location::Update<location::units::Degrees>& heading)
+{
+  std::cout << pos << std::endl;
+});
+
+session->updates().velocity.changed().connect([this](const location::Update<location::units::MetersPerSecond>& velocity)
+{
+  std::cout << pos << std::endl;
+});
+
+session->updates().position_status = location::Service::Session::Updates::Status::enabled;
+session->updates().heading_status = location::Service::Session::Updates::Status::enabled;
+session->updates().velocity_status = location::Service::Session::Updates::Status::enabled;
+```

=== added file 'doc/cli.md'
--- doc/cli.md	1970-01-01 00:00:00 +0000
+++ doc/cli.md	2016-09-22 10:48:21 +0000
@@ -0,0 +1,11 @@
+# CLI
+
+The location service offers a command-line interface for controlling
+and monitoring the service. The following commands are available:
+
+ - list: Lists all provider implementations known to the service.
+ - monitor: Connects to a location service instance, monitoring its activity.
+ - provider: Executes a known provider implementation in an out-of-process sandbox.
+ - run: Executes the service.
+ - status: Queries the status of a service instance.
+ - test: Executes runtime tests against known provider implementations.

=== modified file 'doc/index.rst'
--- doc/index.rst	2016-08-26 13:26:52 +0000
+++ doc/index.rst	2016-09-22 10:48:21 +0000
@@ -12,12 +12,9 @@
    :maxdepth: 2
 
    intro
+   cli
+   api
    hacking
-   debugging
-   daemon_and_cli
-   manual_testing
-   tips_n_tricks
-
 
 Indices and tables
 ==================

=== modified file 'doc/intro.md'
--- doc/intro.md	2016-08-26 13:41:21 +0000
+++ doc/intro.md	2016-09-22 10:48:21 +0000
@@ -11,27 +11,25 @@
 To make the remainder of this documentation as easily understandable
 as possible, we start over with introducing some vocabulary:
 
-- Engine: 
-    Responsible for handling input from multiple positioning
-    subsystems and maintaining the state of the overall system. Think
-    about it like the heart of the system.
-
-- Provider: 
-    A positioning subsystem that feeds into the positioning
-    engine. Common examples are a GPS provider or a network-based
-    positioning provider.
-
-- Service:
-    The point of entry for applications and services that would
-    like to receive position data.
-
-- Session:
-    In order to receive position information, every application
-    or service has to create a session with the location Service.
+ - Engine: Responsible for handling input from multiple positioning
+   subsystems and maintaining the state of the overall system. Think
+   about it like the heart of the system.
+
+ - Provider: A positioning subsystem that feeds into the positioning
+   engine. Common examples are a GPS provider or a network-based
+   positioning provider.
+
+ - Service: The point of entry for applications and services that would
+   like to receive position data.
+
+ - Session: In order to receive position information, every application
+   or service has to create a session with the location Service.
+   Session creation is subject to security mediation and contextual
+   prompting.
 
 - Update: An update is a timestamped entity to a certain type of data.
 
-- [WGS84, http://en.wikipedia.org/wiki/World_Geodetic_System]: The coordinate system that is used throughout the entire location subsystem.
+- [WGS84](http://en.wikipedia.org/wiki/World_Geodetic_System): The coordinate system that is used throughout the entire location subsystem.
 
 ## Architectural Overview
 
@@ -48,7 +46,16 @@
 The Service takes this configuration and exposes it to client
 applications. In addition, mainly for debugging purposes, the set of
 currently visible satellites (if any) is maintained and exposed to
-privileged client applications.
+privileged client applications. The service supports multiple different satellite-based 
+positioning operating in parallel. The following GNSSs are known:
+
+  * Beidou: People's Republic of China's regional system, currently limited to Asia and the West Pacific.
+  * Galileo: A global system being developed by the European Union and other partner countries, planned to be operational by 2014 (and fully deployed by 2019).
+  * Glonass: Russia's global navigation system. Fully operational worldwide.
+  * GPS: Fully operational worldwide.
+  * Compass: People's Republic of China's global system, planned to be operational by 2020.
+  * IRNSS: India's regional navigation system, planned to be operational by 2014, covering India and Northern Indian Ocean.
+  * QZSS: Japanese regional system covering Asia and Oceania.
 
 ## Privacy & Access Control