diff --git a/.gitignore b/.gitignore
index bdd5055d1..a5e2becbb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -67,3 +67,7 @@ target/
 .idea/*
 *.iml
 .vscode
+
+# created by sphinx documentation build
+doc/source/README.md
+doc/_build
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 000000000..d5b5edf76
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,21 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -c source
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = kubernetes-python
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+html:
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "\nDocs rendered successfully, open _/build/html/index.html to view"
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 000000000..5b635c577
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,11 @@
+Building the documentation
+==========================
+
+Install the test requirements with:
+
+```
+$ pip install -r ../test-requirements.txt
+```
+
+Use `make html` to build the docs in html format.
+
diff --git a/doc/requirements-docs.txt b/doc/requirements-docs.txt
new file mode 100644
index 000000000..eb69200af
--- /dev/null
+++ b/doc/requirements-docs.txt
@@ -0,0 +1,2 @@
+recommonmark
+sphinx_markdown_tables
diff --git a/doc/source/conf.py b/doc/source/conf.py
index a5f0a1fc6..2d1d6acc9 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -13,22 +13,37 @@
 # limitations under the License.
 
 import os
+import re
+import shutil
 import sys
 
-from recommonmark.parser import CommonMarkParser
+from recommonmark.transform import AutoStructify
+
+# Work around https://github.com/readthedocs/recommonmark/issues/152
+new_readme = []
+
+with open("../../README.md", "r") as r:
+    lines = r.readlines()
+    for l in lines:
+        nl = re.sub("\[!\[[\w\s]+\]\(", "[![](", l)
+        new_readme.append(nl)
+
+with open("README.md", "w") as n:
+    n.writelines(new_readme)
+
+# apparently index.rst can't search for markdown not in the same directory
+shutil.copy("../../CONTRIBUTING.md", ".")
 
 sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ----------------------------------------------------
 
-source_parsers = {
-    '.md': CommonMarkParser,
-}
-
 source_suffix = ['.rst', '.md']
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    'sphinx_markdown_tables',
+    'recommonmark',
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
 ]
@@ -80,3 +95,10 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'http://docs.python.org/': None}
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+            'auto_toc_tree_section': 'Contents',
+            'enable_eval_rst': True,
+            }, True)
+    app.add_transform(AutoStructify)
+
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
deleted file mode 100644
index 2a4789889..000000000
--- a/doc/source/contributing.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-============
-Contributing
-============
-.. include:: ../../CONTRIBUTING.md
diff --git a/doc/source/index.rst b/doc/source/index.rst
index fc6b82629..038a82f72 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -11,11 +11,11 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   readme
+   README <README.md>
    installation
    usage
    modules
-   contributing
+   contributing <CONTRIBUTING.md>
 
 Indices and tables
 ==================
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index 77f974f64..000000000
--- a/doc/source/readme.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-======
-Readme
-======
-.. include:: ../../README.md
diff --git a/setup.py b/setup.py
index ec50eb2de..aa4a33b66 100644
--- a/setup.py
+++ b/setup.py
@@ -62,9 +62,7 @@
               'kubernetes.stream', 'kubernetes.client.models',
               'kubernetes.utils'],
     include_package_data=True,
-    long_description="""\
-    Python client for kubernetes http://kubernetes.io/
-    """,
+    long_description="Python client for kubernetes http://kubernetes.io/",
     classifiers=[
         "Development Status :: %s" % DEVELOPMENT_STATUS,
         "Topic :: Utilities",
diff --git a/test-requirements.txt b/test-requirements.txt
index 0bb8dc53c..6200389e4 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -5,9 +5,10 @@ pluggy>=0.3.1
 py>=1.4.31
 randomize>=0.13
 mock>=2.0.0
-sphinx>=1.2.1,!=1.3b1,<1.4 # BSD
+sphinx>=1.4 # BSD
 recommonmark
+sphinx_markdown_tables
 codecov>=1.4.0
 pycodestyle
 autopep8
-isort
\ No newline at end of file
+isort