Merge pull request #2013 from tomplus/feat/update-doc

[doc] update Sphinx configuration

.gitignore

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

doc/.gitignore

@@ -0,0 +1,4 @@
+source/README.md
+source/CONTRIBUTING.md
+source/kubernetes.*
+build

doc/Makefile

@@ -2,6 +2,7 @@
 #
 
 # You can set these variables from the command line.
+SPHINXAPIDOC  = sphinx-apidoc
 SPHINXOPTS    = -c source
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = kubernetes-python
@@ -17,5 +18,6 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 html:
+	$(SPHINXAPIDOC) -o "$(SOURCEDIR)" ../kubernetes/ -e -f
 	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	@echo "\nDocs rendered successfully, open _/build/html/index.html to view"

doc/source/conf.py

@@ -14,25 +14,31 @@
 
 import os
 import re
-import shutil
 import sys
 
 from recommonmark.transform import AutoStructify
 
-# Work around https://github.com/readthedocs/recommonmark/issues/152
-new_readme = []
+# --
+# Copy README.md, CONTRIBUTING.md to source/ directory and replace
+# all paths to point github files.
+def _copy_with_converting_link_to_repo(filename, new_filename):
+    base_url = 'https://github.com/kubernetes-client/python/blob/master/'
 
-with open("../../README.md", "r") as r:
-    lines = r.readlines()
-    for l in lines:
-        nl = re.sub("\[!\[[\w\s]+\]\(", "[![](", l)
-        new_readme.append(nl)
+    def subf(subs):
+        label, url = subs.groups()
+        if not url.startswith('http://') and not url.startswith('https://'):
+            url = base_url + url
+        return label + '(' + url + ')'
 
-with open("README.md", "w") as n:
-    n.writelines(new_readme)
+    with open(filename, "r") as r:
+        data = re.sub("(\[[^\]]+\])\(([^\)]+)\)", subf, r.read())
 
-# apparently index.rst can't search for markdown not in the same directory
-shutil.copy("../../CONTRIBUTING.md", ".")
+    with open(new_filename, "w") as w:
+        w.write(data)
+
+_copy_with_converting_link_to_repo("../../README.md", "README.md")
+_copy_with_converting_link_to_repo("../../CONTRIBUTING.md", "CONTRIBUTING.md")
+# --
 
 sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ----------------------------------------------------