Move conf.py into the html directory, to be compatible with RTD

Also add a small comment explaining why this has been done.

docs/conf.py → docs/html/conf.py

@@ -18,11 +18,11 @@
 
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
-here = os.path.dirname(__file__)
+docs_dir = os.path.dirname(os.path.dirname(__file__))
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, here)
+sys.path.insert(0, docs_dir)
 # sys.path.append(os.path.join(os.path.dirname(__file__), '../'))
 
 # -- General configuration ----------------------------------------------------
@@ -70,7 +70,7 @@
 # read the version direct from the __init__.py file. (Yes, this is
 # fragile, but it works...)
 
-pip_init = os.path.join(here, '..', 'src', 'pip', '__init__.py')
+pip_init = os.path.join(docs_dir, '..', 'src', 'pip', '__init__.py')
 with open(pip_init) as f:
     for line in f:
         m = re.match(r'__version__ = "(.*)"', line)

tox.ini

@@ -21,10 +21,14 @@ commands = pytest --timeout 300 --cov=pip --cov-report=term-missing --cov-report
 [testenv:docs]
 # Don't skip install here since pip_sphinxext uses pip's internals.
 deps = -r{toxinidir}/tools/docs-requirements.txt
-basepython = python3.6
+basepython = python2.7
 commands =
-    sphinx-build -W -c docs -d {envtmpdir}/doctrees/html -b html docs/html docs/build/html
-    sphinx-build -W -c docs -d {envtmpdir}/doctrees/man  -b man  docs/man  docs/build/man
+    sphinx-build -W -d {envtmpdir}/doctrees/html -b html docs/html docs/build/html
+    # Having the conf.py in the docs/html is weird but needed because we
+    # can not use a different configuration directory vs source directory on RTD
+    # currently -- https://github.com/rtfd/readthedocs.org/issues/1543.
+    # That is why we have a "-c docs/html" in the next line.
+    sphinx-build -W -d {envtmpdir}/doctrees/man -b man docs/man docs/build/man -c docs/html
 
 [testenv:packaging]
 skip_install = True