diff --git a/README.md b/README.md
index 891f83c9e3b4c554cd11f14cb04061606908ed43..6d3592de47aabdc82f3ce79c078f7408a3d699de 100644
--- a/README.md
+++ b/README.md
@@ -1,140 +1,7 @@
# TANGO Docker containers
-This repository defines a set of Docker images and Docker compose files that
-are useful for TANGO control system development.
+This project defines a set of Docker images and Docker compose files
+that are useful for TANGO control system development.
-## Building the Docker images
-The following Docker images are built by this project:
-
-Docker image | Description
--------------------|------------
-tango-dependencies | A base image containing TANGO's preferred version of ZeroMQ plus the preferred, patched version of OmniORB.
-tango-db | A MariaDB image including TANGO database schema. Data is stored separately in a volume.
-tango-cpp | Core C++ TANGO libraries and applications.
-tango-java | As per ska/tango-cpp, plus Java applications and bindings
-tango-python | Extends ska/tango-cpp, adding PyTango Python bindings and itango for interactive TANGO sessions.
-tango-pogo | Image for running Pogo and displaying Pogo help. Pogo output can be persisted to a docker volume or to the host machine.
-tango-starter | Example image that demonstrates how to package the Starter device in an image.
-
-To build and register the images locally, from the root of this repository
-execute:
-
- cd docker
- # build and register TBC/tango-cpp, TBC/tango-jive, etc. locally
- make build
-
-Optionally, you can register images to an alternative Docker registry account
-by supplying the ``DOCKER_REGISTRY_HOST`` and ``DOCKER_REGISTRY_USER``
-Makefile variables, e.g.,
-
- # build and register images as foo/tango-cpp, foo/tango-jive, etc.
- make DOCKER_REGISTRY_USER=foo build
-
-Push the built images to a Docker registry using ``make push`` target. The
-URL of the registry can be specified by providing the ``DOCKER_REGISTRY_HOST``
-Makefile argument.
-
- # push the images to the Docker registry, making them publicly
- # available as foo/tango-cpp, foo/tango-jive, etc.
- make DOCKER_REGISTRY_USER=foo DOCKER_REGISTRY_HOST=docker.io push
-
-
-## Launching TANGO applications and services
-The docker-compose directory contains a set of files that can be used to run a
-TANGO system in Docker containers. The following services are defined:
-
-Docker service | Description
-----------------|------------
-tangodb | MariaDB database holding TANGO database tables
-databaseds | TANGO database device server
-tangotest | TANGO test device
-jive | Container running Jive application
-logviewer | Container running TANGO log viewer
-pogo | Pogo TANGO application
-astor | Astor application
-starter-example | Example service running TANGO Starter device
-itango | interactive itango session
-
-To pull pre-built images from the Docker hub, execute:
-
- cd docker-compose
- # download official SKA images
- make pull
-
-Optional: the images can be pulled from an alternative account by supplying
-the DOCKER_REGISTRY_USER Makefile variable, e.g.,
-
- cd docker-compose
- # download foo/tango-cpp, foo/tango-jive, etc.
- make DOCKER_REGISTRY_USER=foo pull
-
-To start and stop a minimal TANGO system (database and databaseds server),
-execute:
-
- cd docker-compose
- # start a minimal TANGO system with database and TANGO database server
- make up
-
-Optional applications and device servers can be launched by calling the
-_start_ make target followed by the name of the service. For example:
-
- # still in the docker-compose directory..
- # run Jive
- make start jive
- # run tangotest
- make start tangotest
-
-Running services can be stopped individually or as a whole using the _stop_
-make target or _down_ make target respectively. For instance,
-
- # stop just the tangotest device server, leaving other services running
- make stop tangotest
- # stop all services and tear down the system
- make down
-
-## Interacting with TANGO applications and devices
-
-### Command line interactions
-``itango`` can be used for command line interactions with the system. To make
-itango available, launch the itango service and attach the terminal to the
-itango container. An example session follows:
-
- # start the tangotest device, which we'll connect to using itango
- make start tangotest
- # start the itango container
- make start itango
- # attach to the itango container
- docker attach itango
- In [1]: dev = DeviceProxy('sys/tg_test/1')
-
- In [2]: dev.string_scalar
- Out[2]: 'Default string'
-
- ...
-
-To detach from the session without quitting the itango session, press the key
-combination <CTRL+P><CTRL+Q>.
-
-### GUI interactions
-Graphical applications such as Jive and Pogo can be run in a container,
-sending their output to an X11 server running on the host machine.
-
- # run Jive, using the default IP address determined by the Makefile
- make start jive
- # run Pogo
- make start pogo
-
-GUI applications send X11 traffic to an IP address determined by the makefile.
-This IP address can be overridden by passing a ``DISPLAY`` variable to make,
-e.g.,
-
- # run Jive, sending X11 output to 172.16.10.120:0
- make DISPLAY=172.16.10.120:0 start jive
-
-Note that the IP address is evaluated inside the Docker container, hence
-127.0.0.1 would direct output to the container itself.
-
-#### Exporting Pogo output
-The Pogo service mounts your home directory as ``/hosthome``. Save Pogo
-output to the ``/hosthome`` directory to make it available outside the
-container.
\ No newline at end of file
+See the documentation in the ``docs`` folder for build and usage
+instructions.
diff --git a/docs/Makefile b/docs/Makefile
index 95aeeead65b7216247271b6842aa097bf384382e..4164814c011579259a8076044396258e843722ed 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -5,7 +5,7 @@
SPHINXOPTS =
SPHINXBUILD = python -msphinx
SPHINXPROJ = skeleton
-SOURCEDIR = source
+SOURCEDIR = src
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
diff --git a/docs/source/_static/css/custom.css b/docs/src/_static/css/custom.css
similarity index 100%
rename from docs/source/_static/css/custom.css
rename to docs/src/_static/css/custom.css
diff --git a/docs/source/_static/img/favicon.ico b/docs/src/_static/img/favicon.ico
similarity index 100%
rename from docs/source/_static/img/favicon.ico
rename to docs/src/_static/img/favicon.ico
diff --git a/docs/source/_static/img/logo.jpg b/docs/src/_static/img/logo.jpg
similarity index 100%
rename from docs/source/_static/img/logo.jpg
rename to docs/src/_static/img/logo.jpg
diff --git a/docs/source/_static/img/logo.svg b/docs/src/_static/img/logo.svg
similarity index 100%
rename from docs/source/_static/img/logo.svg
rename to docs/src/_static/img/logo.svg
diff --git a/docs/source/_templates/footer.html b/docs/src/_templates/footer.html
similarity index 100%
rename from docs/source/_templates/footer.html
rename to docs/src/_templates/footer.html
diff --git a/docs/source/_templates/layout.html b/docs/src/_templates/layout.html
similarity index 100%
rename from docs/source/_templates/layout.html
rename to docs/src/_templates/layout.html
diff --git a/docs/source/conf.py b/docs/src/conf.py
similarity index 91%
rename from docs/source/conf.py
rename to docs/src/conf.py
index 146bb9b38aa4056aefc5d66eda5c9590fcdfcdff..2b476a6a7fa2a9f4e3da5f232f6334c242d2341d 100644
--- a/docs/source/conf.py
+++ b/docs/src/conf.py
@@ -53,9 +53,9 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
-project = 'Skeleton project'
-copyright = '2018, Marco Bartolini'
-author = 'Marco Bartolini'
+project = 'SKA Docker Images'
+copyright = '2018, Stewart Williams'
+author = 'Stewart Williams'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -100,13 +100,12 @@ html_theme = 'sphinx_rtd_theme'
html_context = {
'favicon': 'img/favicon.ico',
'logo': 'img/logo.jpg',
- 'theme_logo_only' : True,
- 'display_github': True, # Integrate GitHub
- 'github_user': 'flyingfrog81', # Username
- 'github_repo': 'ska-skeleton', # Repo name
- 'github_version': 'master', # Version
- 'conf_py_path': '/docs/src/', # Path in the checkout to the docs root
-
+ 'theme_logo_only': True,
+ 'display_github': True, # Integrate GitHub
+ 'github_user': 'ska-telescope', # Username
+ 'github_repo': 'docker', # Repo name
+ 'github_version': 'master', # Version
+ 'conf_py_path': '/docs/src/', # Path in the checkout to the docs root
}
# Add any paths that contain custom static files (such as style sheets) here,
@@ -171,7 +170,7 @@ latex_documents = [
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, '{{project-name}}', '{{project-name}} Documentation',
- [{{author}}], 1)
+ ['{{author}}'], 1)
]
@@ -182,7 +181,7 @@ man_pages = [
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, '{{project-name}}', '{{project-name}} Documentation',
- {{author}}, '{{project-name}}', 'One line description of project.',
+ '{{author}}', '{{project-name}}', 'One line description of project.',
'Miscellaneous'),
]
diff --git a/docs/src/docker_compose.rst b/docs/src/docker_compose.rst
new file mode 100644
index 0000000000000000000000000000000000000000..c6a885d21d327921ec81bf7ea763b10e44d60c5e
--- /dev/null
+++ b/docs/src/docker_compose.rst
@@ -0,0 +1,76 @@
+Launching TANGO applications and services in containers
+=======================================================
+
+The docker-compose directory contains a set of files that can be used to
+run a TANGO system in Docker containers. The following services are
+defined:
+
++-----------------+------------------------------------------------+
+| Docker service | Description |
++=================+================================================+
+| tangodb | MariaDB database holding TANGO database tables |
++-----------------+------------------------------------------------+
+| databaseds | TANGO database device server |
++-----------------+------------------------------------------------+
+| tangotest | TANGO test device |
++-----------------+------------------------------------------------+
+| jive | Container running Jive application |
++-----------------+------------------------------------------------+
+| logviewer | Container running TANGO log viewer |
++-----------------+------------------------------------------------+
+| pogo | Pogo TANGO application |
++-----------------+------------------------------------------------+
+| astor | Astor application |
++-----------------+------------------------------------------------+
+| starter-example | Example service running TANGO Starter device |
++-----------------+------------------------------------------------+
+| itango | interactive itango session |
++-----------------+------------------------------------------------+
+
+To pull pre-built images from the Docker hub, execute:
+
+.. code-block:: console
+
+ cd docker-compose
+ # download official SKA images
+ make pull
+
+Optional: the images can be pulled from an alternative account by
+supplying the DOCKER_REGISTRY_USER Makefile variable, e.g.,
+
+.. code-block:: console
+
+ cd docker-compose
+ # download foo/tango-cpp, foo/tango-jive, etc.
+ make DOCKER_REGISTRY_USER=foo pull
+
+To start and stop a minimal TANGO system (database and databaseds
+server), execute:
+
+.. code-block:: console
+
+ cd docker-compose
+ # start a minimal TANGO system with database and TANGO database server
+ make up
+
+Optional applications and device servers can be launched by calling the
+*start* make target followed by the name of the service. For example:
+
+.. code-block:: console
+
+ # still in the docker-compose directory..
+ # run Jive
+ make start jive
+ # run tangotest
+ make start tangotest
+
+Running services can be stopped individually or as a whole using the
+*stop* make target or *down* make target respectively. For instance,
+
+.. code-block:: console
+
+ # stop just the tangotest device server, leaving other services running
+ make stop tangotest
+ # stop all services and tear down the system
+ make down
+
diff --git a/docs/src/docker_images.rst b/docs/src/docker_images.rst
new file mode 100644
index 0000000000000000000000000000000000000000..a3f8f9a8702aa41bf52297a4cc91dad7f838a0c8
--- /dev/null
+++ b/docs/src/docker_images.rst
@@ -0,0 +1,62 @@
+Building the Docker images
+==========================
+
+The following Docker images are built by this project:
+
++--------------------+-------------------------------------------------------+
+| Docker image | Description |
++====================+=======================================================+
+| tango-dependencies | A base image containing TANGO's preferred version of |
+| | ZeroMQ plus the preferred, patched version of |
+| | OmniORB. |
++--------------------+-------------------------------------------------------+
+| tango-db | A MariaDB image including TANGO database schema. Data |
+| | is stored separately in a volume. |
++--------------------+-------------------------------------------------------+
+| tango-cpp | Core C++ TANGO libraries and applications. |
++--------------------+-------------------------------------------------------+
+| tango-pogo | Image for running Pogo and displaying Pogo help. Pogo |
+| | output can be persisted to a docker volume or to the |
+| | host machine. |
++--------------------+-------------------------------------------------------+
+| tango-java | As per ska/tango-cpp, plus Java applications and |
+| | bindings |
++--------------------+-------------------------------------------------------+
+| tango-python | Extends ska/tango-cpp, adding PyTango Python bindings |
+| | and itango for interactive TANGO sessions. |
++--------------------+-------------------------------------------------------+
+| tango-starter | Example image that demonstrates how to package the |
+| | Starter device in an image. |
++--------------------+-------------------------------------------------------+
+
+To build and register the images locally, from the root of this
+repository execute:
+
+.. code-block:: console
+
+ cd docker
+ # build and register TBC/tango-cpp, TBC/tango-jive, etc. locally
+ make build
+
+Optionally, you can register images to an alternative Docker registry
+account by supplying the ``DOCKER_REGISTRY_HOST`` and
+``DOCKER_REGISTRY_USER`` Makefile variables, e.g.,
+
+.. code-block:: console
+
+ # build and register images as foo/tango-cpp, foo/tango-jive, etc.
+ make DOCKER_REGISTRY_USER=foo build
+
+Pushing the images to a Docker registry
+---------------------------------------
+
+Push the built images to a Docker registry using ``make push`` target.
+The URL of the registry can be specified by providing the
+``DOCKER_REGISTRY_HOST`` Makefile argument.
+
+.. code-block:: console
+
+ # push the images to the Docker registry, making them publicly
+ # available as foo/tango-cpp, foo/tango-jive, etc.
+ make DOCKER_REGISTRY_USER=foo DOCKER_REGISTRY_HOST=docker.io push
+
diff --git a/docs/source/index.rst b/docs/src/index.rst
similarity index 63%
rename from docs/source/index.rst
rename to docs/src/index.rst
index 534294648c18b6af4d0f58a9629b1ee5dc32d37a..22204e14b6a1deabe17ade85a1b43407ffe63719 100644
--- a/docs/source/index.rst
+++ b/docs/src/index.rst
@@ -3,14 +3,19 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Skeleton Project
-================
+SKA Docker Images
+=================
+
+This project defines a set of Docker images and Docker compose files
+that are useful for TANGO control system development.
.. toctree::
:maxdepth: 2
:caption: Contents:
-
+ docker_images
+ docker_compose
+ interactions
Indices and tables
==================
diff --git a/docs/src/interactions.rst b/docs/src/interactions.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f261f606d104dd74a29a1110c324833d2c6d9789
--- /dev/null
+++ b/docs/src/interactions.rst
@@ -0,0 +1,59 @@
+Interacting with TANGO applications and devices
+===============================================
+
+Command line interactions
+-------------------------
+
+``itango`` can be used for command line interactions with the system. To
+make itango available, launch the itango service and attach the terminal
+to the itango container. An example session follows:
+
+::
+
+ # start the tangotest device, which we'll connect to using itango
+ make start tangotest
+ # start the itango container
+ make start itango
+ # attach to the itango container
+ docker attach itango
+ In [1]: dev = DeviceProxy('sys/tg_test/1')
+
+ In [2]: dev.string_scalar
+ Out[2]: 'Default string'
+
+ ...
+
+To detach from the session without quitting the itango session, press
+the key combination <CTRL+P><CTRL+Q>.
+
+GUI interactions
+----------------
+
+Graphical applications such as Jive and Pogo can be run in a container,
+sending their output to an X11 server running on the host machine.
+
+::
+
+ # run Jive, using the default IP address determined by the Makefile
+ make start jive
+ # run Pogo
+ make start pogo
+
+GUI applications send X11 traffic to an IP address determined by the
+makefile. This IP address can be overridden by passing a ``DISPLAY``
+variable to make, e.g.,
+
+::
+
+ # run Jive, sending X11 output to 172.16.10.120:0
+ make DISPLAY=172.16.10.120:0 start jive
+
+Note that the IP address is evaluated inside the Docker container, hence
+127.0.0.1 would direct output to the container itself.
+
+Exporting Pogo output
+---------------------
+
+The Pogo service mounts your home directory as ``/hosthome``. Save Pogo
+output to the ``/hosthome`` directory to make it available outside the
+container.
\ No newline at end of file