Mulitple docs fixes

 *  Document how to build the doumentation with sphinx

    For convinience, I added a Makefile which spares one to memorize the
    long sphinx command, or type python setup.py build_sphinx

    You simply use `make html` and you will get the docs.

 * Render README with markdown properly

   conf.py includes some code to work around a  bug in
   common mark. The markdown is now properly converted to HTML.

 * Fix rendering of CONTRIBUTING.md

Author: oz123

.gitignore

@@ -67,3 +67,7 @@ target/
 .idea/*
 *.iml
 .vscode
+
+# created by sphinx documentation build
+doc/source/README.md
+doc/_build

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"

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.
+

doc/requirements-docs.txt

@@ -0,0 +1,2 @@
+recommonmark
+sphinx_markdown_tables

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)
+

doc/source/contributing.rst

@@ -11,11 +11,11 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   readme
+   README <README.md>
    installation
    usage
    modules
-   contributing
+   contributing <CONTRIBUTING.md>
 
 Indices and tables
 ==================

doc/source/index.rst

@@ -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",

doc/source/readme.rst

@@ -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
+isort