Merge pull request tox-dev#34 from stephenfin/add-docs

Add Sphinx for documentation

README.rst

@@ -0,0 +1,85 @@
+============
+ tox-docker
+============
+
+A `tox <https://tox.readthedocs.io/en/latest/>`__ plugin which runs one or
+more `Docker <https://www.docker.com/>`__ containers during the test run.
+
+.. image:: https://travis-ci.org/tox-dev/tox-docker.svg?branch=master
+   :target: https://travis-ci.org/tox-dev/tox-docker
+   :alt: Build Status
+
+Usage and Installation
+----------------------
+
+tox loads all plugins automatically. It is recommended that you install the
+tox-docker plugin into the same Python environment as you install tox into,
+whether that's a virtualenv, etc.
+
+You do not need to do anything special when running tox to invoke
+tox-docker. You do need to configure your project to request docker
+instances (see "Configuration" below).
+
+Configuration
+-------------
+
+In the ``testenv`` section, list the Docker images you want to include in
+the ``docker`` multi-line-list. Be sure to include the version tag.
+
+You can include environment variables to be passed to the docker container
+via the ``dockerenv`` multi-line list. These will also be made available to
+your test suite as it runs, as ordinary environment variables::
+
+    [testenv]
+    docker =
+        postgres:9-alpine
+    dockerenv =
+        POSTGRES_USER=username
+        POSTGRES_DB=dbname
+
+Host and Port Mapping
+---------------------
+
+tox-docker runs docker with the "publish all ports" option. Any port the
+container exposes will be made available to your test suite via environment
+variables of the form ``<image-basename>_<exposed-port>_<protocol>_PORT``.
+For instance, for the PostgreSQL container, there will be an environment
+variable ``POSTGRES_5432_TCP_PORT`` whose value is the ephemeral port number
+that docker has bound the container's port 5432 to.
+
+Likewise, exposed UDP ports will have environment variables like
+``TELEGRAF_8092_UDP_PORT`` Since it's not possible to check whether UDP port
+is open it's just mapping to environment variable without any checks that
+service up and running.
+
+The host name for each service is also exposed via environment as
+``<image-basename>_HOST``, which is ``POSTGRES_HOST`` and ``TELEGRAF_HOST`` for
+the two examples above.
+
+*Deprecation Note:* In older versions of tox-docker, the port was exposed as
+``<image-basename>-<exposed-port>-<protocol>``. This additional environment
+variable is deprecated, but will be supported until tox-docker 2.0.
+
+Health Checking
+---------------
+
+As of version 1.4, tox-docker uses Docker's health checking to determine
+when a container is fully running, before it begins your test. For Docker
+images that contain a ``HEALTHCHECK`` command, tox-docker uses that.
+
+You may also specify a custom health check in ``tox.ini``, in a new section
+like::
+
+    [docker:redis:5.0-alpine]
+    healthcheck_cmd = redis-cli ping | grep -q PONG
+    healthcheck_interval = 1
+    healthcheck_timeout = 1
+    healthcheck_retries = 30
+    healthcheck_start_period = 0.5
+
+The image name -- everything after the ``docker:`` in the section header --
+must *exactly* match the image name used in your testenv's ``docker`` setting.
+
+tox-docker will print a message for each container that it is waiting on a
+health check from, whether via the container's built-in ``HEALTHCHECK`` or a
+custom health check.

docs/source/conf.py

@@ -0,0 +1,36 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+import os
+
+import vcversioner
+
+
+ROOT_DIR = os.path.dirname(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'tox-docker'
+copyright = '2019, Dan Crosta'
+author = 'Dan Crosta'
+version = release = vcversioner.find_version(root=ROOT_DIR).version
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'

docs/source/index.rst

@@ -0,0 +1 @@
+.. include:: ../../README.rst

tox.ini

@@ -7,6 +7,15 @@ envlist = integration,registry,healthcheck-builtin,healthcheck-custom
 commands_pre = python capture_containers_and_volumes.py
 commands_post = python assert_containers_and_volumes_unchanged.py
 
+[testenv:docs]
+deps =
+    sphinx
+    sphinx_rtd_theme
+    vcversioner
+commands = sphinx-build -W -b html docs/source docs/build/html
+commands_pre =
+commands_post =
+
 [testenv:integration]
 docker =
     nginx:1.13-alpine