Improve docs build process

Remove Python 2 stuff as well as unused or commented out configuration
values. Also add sphinx to the dependencies

Signed-off-by: Stephen Finucane <[email protected]>

Author: stephenfin

doc/Makefile

@@ -19,4 +19,4 @@ help:
 # "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"
+	@echo "Docs rendered successfully, open _/build/html/index.html to view"

doc/README.md

@@ -8,4 +8,3 @@ $ pip install -r ../test-requirements.txt
 ```
 
 Use `make html` to build the docs in html format.
-

doc/requirements-docs.txt

@@ -1,2 +1,3 @@
+sphinx
 recommonmark
 sphinx_markdown_tables

doc/source/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -18,29 +17,7 @@
 
 from recommonmark.transform import AutoStructify
 
-# --
-# 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/'
-
-    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(filename, "r") as r:
-        data = re.sub("(\[[^\]]+\])\(([^\)]+)\)", subf, r.read())
-
-    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 ----------------------------------------------------
 
 source_suffix = ['.rst', '.md']
@@ -50,23 +27,17 @@ def subf(subs):
 extensions = [
     'sphinx_markdown_tables',
     'recommonmark',
-    'sphinx.ext.autodoc',
-    #'sphinx.ext.intersphinx',
 ]
 
-# autodoc generation is a bit aggressive and a nuisance when doing heavy
-# text edit cycles.
-# execute "export SPHINX_DEBUG=1" in your terminal to disable
-
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
-project = u'kubernetes-python-client'
-copyright = u'2017, Kubernetes'
+project = 'kubernetes-python-client'
+copyright = '2017-present, Kubernetes'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
@@ -78,33 +49,36 @@ def subf(subs):
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# -- Options for HTML output --------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-# html_theme_path = ["."]
-# html_theme = '_theme'
-# html_static_path = ['static']
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = '%sdoc' % project
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass
-# [howto/manual]).
-latex_documents = [
-    ('index',
-     '%s.tex' % project,
-     u'%s Documentation' % project,
-     u'Kubernetes', 'manual'),
-]
 
-# Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
+# 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/'
+
+    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(filename, "r") as r:
+        data = re.sub("(\[[^\]]+\])\(([^\)]+)\)", subf, r.read())
+
+    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")
+
+
 def setup(app):
-    app.add_config_value('recommonmark_config', {
+    app.add_config_value(
+        'recommonmark_config',
+        {
             'auto_toc_tree_section': 'Contents',
             'enable_eval_rst': True,
-            }, True)
+        },
+        True,
+    )
     app.add_transform(AutoStructify)
-

test-requirements.txt

@@ -4,7 +4,6 @@ pytest
 pytest-cov
 pluggy>=0.3.1
 randomize>=0.13
-sphinx>=1.4 # BSD
 recommonmark
 sphinx_markdown_tables
 pycodestyle