Update documentation (#88)

* Add information regarding dev environment (fixes #77).

* Update requirements and README.

* Remove unused quick-start file.

* Move docs closer to code.

* Add documentation build to CI.

* Fix linting errors.

Author: tillahoffmann

.travis.yml

@@ -29,6 +29,7 @@ before_script: # add the mssql driver for xenial
 
 script:
   - flake8
+  - sphinx-build -nW docs docs/_build/html
   - py.test -sv --cov-config .coveragerc --cov-report html:skip-covered --cov-report term:skip-covered --cov=testcontainers --tb=short tests/
   - codecov
 

README.md

@@ -0,0 +1,67 @@
+testcontainers-python
+=====================
+
+.. image:: https://travis-ci.org/testcontainers/testcontainers-python.svg?branch=master
+   :target: https://travis-ci.org/testcontainers/testcontainers-python
+.. image:: https://img.shields.io/pypi/v/testcontainers.svg?style=flat-square
+   :target: https://pypi.python.org/pypi/testcontainers
+.. image:: https://readthedocs.org/projects/testcontainers-python/badge/?version=latest
+   :target: http://testcontainers-python.readthedocs.io/en/latest/?badge=latest
+
+Python port for testcontainers-java that allows using docker containers for functional and integration testing. Testcontainers-python provides capabilities to spin up docker containers (such as a database, Selenium web browser, or any other container) for testing.
+
+Currently available features:
+
+* Selenium Grid containers
+* Selenium Standalone containers
+* MySql Db container
+* MariaDb container
+* OracleDb container
+* PostgreSQL Db container
+* Microsoft SQL Server container
+* Generic docker containers
+
+Installation
+------------
+
+The testcontainers package is available from `PyPI <https://pypi.org/project/testcontainers/>`_, and it can be installed using :code:`pip`. Depending on which containers are needed, you can specify additional dependencies as `extras <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`_:
+
+.. code-block:: bash
+
+    # Install without extras
+    pip install testcontainers
+    # Install with one or more extras
+    pip install testcontainers[mysql]
+    pip install testcontainers[mysql,oracle]
+
+Basic usage
+-----------
+
+.. code-block:: python
+
+    import sqlalchemy
+    from testcontainers.mysql import MySqlContainer
+
+    with MySqlContainer('mysql:5.7.17') as mysql:
+        engine = sqlalchemy.create_engine(mysql.get_connection_url())
+        version, = engine.execute("select version()").fetchone()
+        print(version)  # 5.7.17
+
+The snippet above will spin up a MySql database in a container. The :code:`get_connection_url()` convenience method returns a :code:`sqlalchemy` compatible url we use to connect to the database and retrieve the database version.
+
+More extensive documentation can be found at `Read The Docs <http://testcontainers-python.readthedocs.io/>`_.
+
+Setting up a development environment
+------------------------------------
+
+We recommend you use a `virtual environment <https://virtualenv.pypa.io/en/stable/>`_ for development. Note that a python version :code:`>=3.5` is required. After setting up your virtual environment, you can install all dependencies and test the installation by running the following snippet.
+
+.. code-block:: bash
+
+    pip install -r requirements/$(python -c 'import sys; print("%d.%d" % sys.version_info[:2])').txt
+    pytest -s
+
+Adding requirements
+^^^^^^^^^^^^^^^^^^^
+
+We use :code:`pip-tools` to resolve and manage dependencies. If you need to add a dependency to testcontainers or one of the extras, run :code:`pip install pip-tools` followed by :code:`make requirements` to update the requirements files.

README.rst

@@ -1,41 +1,2 @@
-Docker compose support
-======================
-
-Allows to spin up services configured via docker-compose.yml
-
-Example docker-compose.yml for grid
------------------------------------
-
-::
-
-    hub:
-      image: selenium/hub
-    ports:
-      - "4444:4444"
-    firefox:
-      image: selenium/node-firefox
-      links:
-        - hub
-      expose:
-        - "5555"
-    chrome:
-      image: selenium/node-chrome
-      links:
-        - hub
-      expose:
-        - "5555"
-
-Code
-----
-
-::
-
-    compose = DockerCompose("/home/project", pull=True)
-    with compose:
-        host = compose.get_service_host("hub", 4444)
-        port = compose.get_service_port("hub", 4444)
-        driver = webdriver.Remote(
-            command_executor=("http://{}:{}/wd/hub".format(host,port)),
-            desired_capabilities=CHROME)
-        driver.get("http://automation-remarks.com")
-
+.. automodule:: testcontainers.compose
+   :members: DockerCompose

docs/compose.rst

@@ -30,7 +30,10 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -93,7 +96,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------

docs/conf.py

@@ -1,129 +1,12 @@
 Database containers
 ===================
 
-Allows to spin up docker database images such as MySQL, PostgreSQL, MariaDB, Oracle XE and MongoDb.
-
-MySQL example
--------------
-
-::
-
-    def test_docker_run_mysql():
-        config = MySqlContainer('mysql:5.7.17')
-        with config as mysql:
-            e = sqlalchemy.create_engine(mysql.get_connection_url())
-            result = e.execute("select version()")
-
-It will spin up MySQL version 5.7. Then you can connect to database with credentials passed in constructor or just
-
-call ``get_connection_url()`` method which returns sqlalchemy compatible url in format ``dialect+driver://username:password@host:port/database``.
-
-PostgresSQL
------------
-
-Example of PostgresSQL database usage:
-
-::
-
-    def test_docker_run_postgress():
-        postgres_container = PostgresContainer("postgres:9.5")
-        with postgres_container as postgres:
-            e = sqlalchemy.create_engine(postgres.get_connection_url())
-            result = e.execute("select version()")
-
-Connection set by using raw python ``psycopg2`` driver for Postgres.
-
-MariaDB
--------
-
-Maria DB is a fork of MySQL database, so the only difference with MySQL is the name of Docker container.
-
-::
-
-    def test_docker_run_mariadb():
-        mariadb_container = MariaDbContainer("mariadb:latest")
-        with mariadb_container as mariadb:
-            e = sqlalchemy.create_engine(mariadb.get_connection_url())
-            result = e.execute("select version()")
-
-Oracle XE
----------
-
-::
-
-    oracle = OracleDbContainer()
-
-    with oracle:
-        e = sqlalchemy.create_engine(oracle.get_connection_url())
-        result = e.execute("select 1 from dual")
-
-It uses **https://hub.docker.com/r/wnameless/oracle-xe-11g-r2/** docker image.
-
-Necessary to use it:
-
-- ``cx_Oracle``
-- `Oracle client libraries <https://cx-oracle.readthedocs.io/en/latest/user_guide/installation.html>`_
-
-::
-
-    hostname: localhost
-    port: 49161
-    sid: xe
-    username: system
-    password: oracle
-
-Elasticsearch
--------------
-
-::
-
-    es = ElasticSearchContainer()
-    with es:
-        es.get_url()  # gives you the http URL to connect to Elasticsearch
-
-MongoDb
------------
-
-Example of MongoDb database usage:
-
-::
-
-    def test_docker_run_mongodb():
-        mongo_container = MongoDbContainer("mongo:latest")
-        with mongo_container as mongo:
-            db = mongo.get_connection_client().test
-            result = db.restaurants.insert_one(
-                {
-                    "address": {
-                        "street": "2 Avenue",
-                        "zipcode": "10075",
-                        "building": "1480",
-                        "coord": [-73.9557413, 40.7720266]
-                    },
-                    "borough": "Manhattan",
-                    "cuisine": "Italian",
-                    "name": "Vella",
-                    "restaurant_id": "41704620"
-                }
-            )
-            print(result.inserted_id)
-            cursor = db.restaurants.find({"borough": "Manhattan"})
-            for document in cursor:
-                print(document)
-
-Connection is made using pymongo package and MongoClient class.
-Alternatively, you can use get_connection_url method to use the driver that better fits for your use case.
-
-Microsoft SQL Server
---------------------
-
-::
-
-    mssql = SqlServerContainer()
-
-    with mssql:
-        e = sqlalchemy.create_engine(mssql.get_connection_url())
-        result = e.execute("select @@VERSION")
-
-It uses the Microsoft-provided Docker image and requires `ODBC Driver 17 for SQL Server
-<https://docs.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server>`_.
+Allows to spin up database images such as MySQL, PostgreSQL, MariaDB, Oracle XE, or MongoDb.
+
+.. autoclass:: testcontainers.mysql.MySqlContainer
+.. autoclass:: testcontainers.mysql.MariaDbContainer
+.. autoclass:: testcontainers.postgres.PostgresContainer
+.. autoclass:: testcontainers.oracle.OracleDbContainer
+.. autoclass:: testcontainers.elasticsearch.ElasticSearchContainer
+.. autoclass:: testcontainers.mongodb.MongoDbContainer
+.. autoclass:: testcontainers.mssql.SqlServerContainer

docs/database.rst

@@ -1,18 +1,2 @@
-Google Cloud Emulators
-======================
-
-Allows to spin up google cloud emulators, such as PubSub.
-
-PubSub example
---------------
-
-::
-
-    def test_docker_run_pubsub():
-        config = PubSubContainer('google/cloud-sdk:latest')
-        with config as pubsub:
-            publisher = pubsub.get_publisher()
-            topic_path = publisher.topic_path(pubsub.project, "my-topic")
-            topic = publisher.create_topic(topic_path)
-
-The example will spin up a Google Cloud PubSub emulator that you can use for integration tests. The :code:`pubsub` instance provides convenience methods :code:`get_publisher` and :code:`get_subscriber` to connect to the emulator without having to set the environment variable :code:`PUBSUB_EMULATOR_HOST`.
+.. automodule:: testcontainers.google
+   :members: PubSubContainer