Documentation: extract guest functions documentation

Signed-off-by: Maxime Petazzoni <maxime.petazzoni@bulix.org>

docs/guest-functions.md

@@ -0,0 +1,67 @@
+# Guest functions
+
+To make use of the Maestro guest utils functions, you'll need to have
+the Maestro package installed inside your container. You can easily
+achieve this by adding the following to your Dockerfile (select the
+version of Maestro that you need):
+
+```Dockerfile
+ENV DEBIAN_FRONTEND noninteractive
+RUN apt-get update && apt-get install python python-pip
+RUN pip install maestro-ng
+```
+
+This will install the latest available version of Maestro. Feel free to
+change that to any other version of Maestro you like or need by adding
+`==<the_version_you_want>` to the end of the command-line.
+
+Then, from your startup script (in Python), do:
+
+```python
+from maestro.guestutils import *
+```
+
+And you're ready to go!
+
+Here's a summary of the functions available at your disposal that will
+make your life much easier:
+
+  - `get_environment_name()` returns the name of the environment as
+    defined in the description file. Could be useful to namespace
+    information inside ZooKeeper for example.
+  - `get_service_name()` returns the friendly name of the service the
+    container is a member of.
+  - `get_container_name()` returns the friendly name of the container
+    itself.
+  - `get_container_host_address()` returns the IP address or hostname of
+    the host of the container. Useful if your application needs to
+    advertise itself to some service discovery system.
+  - `get_container_internal_address()` returns the IP address assigned
+    to the container itself by Docker (its private IP address).
+  - `get_port(name, default)` will return the exposed (internal) port
+    number of a given named port for the current container instance.
+    This is useful to set configuration parameters for example.
+
+Another very useful function is the `get_node_list` function. It takes
+in a service name and an optional list of port names and returns the
+list of IP addresses/hostname of the containers of that service. For
+each port specified, in order, it will append `:<port number>` to each
+host with the external port number. For example, if you want to return
+the list of ZooKeeper endpoints with their client ports:
+
+```python
+get_node_list('zookeeper', ports=['client'])
+# returns ['zk1.domain.com:2181', 'zk2.domain.com:2181']
+```
+
+Other functions you might need are:
+
+  - `get_specific_host(service, container)`, which can be used to return
+    the hostname or IP address of a specific container from a given
+    service, and
+  - `get_specific_port(service, container, port, default)`, to retrieve
+    the external port number of a specific named port of a given
+    container.
+  - `get_specific_exposed_port(service, container, port, default)`, to
+    retrieve the exposed (internal) port number of a specific named port
+    of a given container.

docs/index.md

@@ -5,7 +5,19 @@ ReadTheDocs. Individual, organized sections will be created
 progressively, as they are restructured and taken out of this main
 document (which used to be the project's README).
 
-# Orchestration
+## Introduction
+
+MaestroNG is an orchestrator of Docker-based, multi-hosts environments.
+Working from a description of your environment, MaestroNG offers
+service-level and container-level controls that rely on Maestro's
+understanding of your declared service dependencies, and placement of
+your containers in your fleet of hosts.
+
+Maestro aims at being simple to use whether you are controlling a few
+containers in a local virtual machine, or hundreds of containers spread
+across as many hosts.
+
+## Orchestration
 
 The orchestration features of Maestro obviously rely on the
 collaboration of the Docker containers that you are controlling with
@@ -18,6 +30,16 @@ Maestro. Maestro basically takes care of two things:
    information it may need to operate in that environment, in particular
    information about its dependencies.
 
+The most common way to integrate your application with Maestro is to
+make your container's entrypoint a simple Python init script that acts
+as the glue between Maestro, the information that it passes through the
+container's environment, and your application. To make this easier to
+write and put together, Maestro provides a set of [Guest
+functions](guest-functions.md) that know how to grok this environment
+information.
+
+----
+
 Let's first look at how environments and services are described, then
 we'll discuss what information Maestro passes down to the containers
 through their environment.
@@ -72,8 +94,8 @@ registries:
     email: maestro-robot@domain.com
 ```
 
-The ship defaults allow you to specify certain ship attribute defaults, like
-timeout, docker_port, and ssh_timeout.
+The ship defaults allow you to specify certain ship attribute defaults,
+like `timeout`, `docker_port`, or `ssh_timeout`.
 
 ```yaml
 ship_defaults:
@@ -691,71 +713,6 @@ services:
           mongodb01: db
 ```
 
-## Guest utils helper functions
-
-To make use of the Maestro guest utils functions, you'll need to have
-the Maestro package installed inside your container. You can easily
-achieve this by adding the following to your Dockerfile (select the
-version of Maestro that you need):
-
-```
-ENV DEBIAN_FRONTEND noninteractive
-RUN apt-get update
-RUN apt-get -y install python python-pip git
-RUN pip install git+git://github.com/signalfuse/maestro-ng
-```
-
-This will install the latest available version of Maestro. Feel free to
-change that to any other version of Maestro you like or need.
-
-Then, from your startup script (in Python), do:
-
-```
-from maestro.guestutils import *
-```
-
-And you're ready to go. Here's a summary of the functions available at
-your disposal that will make your life much easier:
-
-  - `get_environment_name()` returns the name of the environment as
-    defined in the description file. Could be useful to namespace
-    information inside ZooKeeper for example.
-  - `get_service_name()` returns the friendly name of the service the
-    container is a member of.
-  - `get_container_name()` returns the friendly name of the container
-    itself.
-  - `get_container_host_address()` returns the IP address or hostname of
-    the host of the container. Useful if your application needs to
-    advertise itself to some service discovery system.
-  - `get_container_internal_address()` returns the IP address assigned
-    to the container itself by Docker (its private IP address).
-  - `get_port(name, default)` will return the exposed (internal) port
-    number of a given named port for the current container instance.
-    This is useful to set configuration parameters for example.
-
-Another very useful function is the `get_node_list` function. It takes
-in a service name and an optional list of port names and returns the
-list of IP addresses/hostname of the containers of that service. For
-each port specified, in order, it will append `:<port number>` to each
-host with the external port number. For example, if you want to return
-the list of ZooKeeper endpoints with their client ports:
-
-```python
-get_node_list('zookeeper', ports=['client']) -> ['c414.ore1.domain.com:2181', 'c415.ore1.domain.com:2181']
-```
-
-Other functions you might need are:
-
-  - `get_specific_host(service, container)`, which can be used to return
-    the hostname or IP address of a specific container from a given
-    service, and
-  - `get_specific_port(service, container, port, default)`, to retrieve
-    the external port number of a specific named port of a given
-    container.
-  - `get_specific_exposed_port(service, container, port, default)`, to
-    retrieve the exposed (internal) port number of a specific named port
-    of a given container.
-
 ## Working with image registries
 
 When Maestro needs to start a new container, it will do whatever it can