pypa · pfmoore · Oct 7, 2017 · Oct 2, 2017 · Oct 3, 2017 · Oct 3, 2017
diff --git a/.gitignore b/.gitignore
@@ -12,7 +12,7 @@ dist/
 MANIFEST
 
 # Documentation
-docs/_build/
+docs/build/
 
 # mypy
 .mypy_cache/

diff --git a/MANIFEST.in b/MANIFEST.in
@@ -23,7 +23,7 @@ recursive-exclude src/pip/_vendor *.pyi
 
 prune .github
 prune .travis
-prune docs/_build
+prune docs/build
 prune news
 prune contrib
 prune tasks

diff --git a/docs/Makefile b/docs/Makefile
@@ -5,7 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = build
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)

diff --git a/docs/conf.py b/docs/conf.py
@@ -33,7 +33,7 @@
 # intersphinx
 intersphinx_cache_limit = 0
 intersphinx_mapping = {
-    'pypug': ('https://packaging.python.org/en/latest/', None),
+    'pypug': ('https://packaging.python.org/', None),
     'pypa': ('https://www.pypa.io/en/latest/', None),
 }
 
@@ -52,7 +52,7 @@
 
 # General information about the project.
 project = 'pip'
-copyright = '2008-2016, PyPA'
+copyright = '2008-2017, PyPA'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -83,7 +83,7 @@
 
 # List of directories, relative to source directory, that shouldn't be searched
 # for source files.
-exclude_patterns = ['_build/', 'man/']
+exclude_patterns = ['build/', 'man/']
 
 # The reST default role (used for this markup: `text`) to use for all documents
 # default_role = None
@@ -114,19 +114,17 @@
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
-if not on_rtd:
-    try:
-        import sphinx_rtd_theme
-        html_theme = 'sphinx_rtd_theme'
-        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-    except ImportError:
-        pass
+html_theme = "pypa_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    'collapsiblesidebar': True,
+    'externalrefs': True,
+    'navigation_depth': 2,
+    'issues_url': 'https://github.com/pypa/pip/issues'
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 
@@ -157,10 +155,13 @@
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
-# html_use_smartypants = False
+smart_quotes = False
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+html_sidebars = {
+    '**': ['localtoc.html', 'relations.html'],
+    'index': ['localtoc.html']
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

diff --git a/docs/index.rst b/docs/index.rst
@@ -12,7 +12,7 @@ The `PyPA recommended <https://packaging.python.org/en/latest/current/>`_ tool
 for installing Python packages.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    quickstart
    installing

diff --git a/docs/make.bat b/docs/make.bat
@@ -5,7 +5,7 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set BUILDDIR=_build
+set BUILDDIR=build
 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
 set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -3,7 +3,7 @@ Reference Guide
 ===============
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    pip
    pip_install

diff --git a/docs/reference/pip.rst b/docs/reference/pip.rst
@@ -1,8 +1,6 @@
 pip
 ---
 
-.. contents::
-
 Usage
 *****
 

diff --git a/docs/reference/pip_check.rst b/docs/reference/pip_check.rst
@@ -3,8 +3,6 @@
 pip check
 ---------
 
-.. contents::
-
 Usage
 *****
 

diff --git a/docs/reference/pip_config.rst b/docs/reference/pip_config.rst
@@ -4,8 +4,6 @@
 pip config
 ------------
 
-.. contents::
-
 Usage
 *****
 

diff --git a/docs/reference/pip_download.rst b/docs/reference/pip_download.rst
@@ -4,8 +4,6 @@
 pip download
 ------------
 
-.. contents::
-
 Usage
 *****
 

diff --git a/docs/reference/pip_freeze.rst b/docs/reference/pip_freeze.rst
@@ -4,8 +4,6 @@
 pip freeze
 -----------
 
-.. contents::
-
 Usage
 *****
 

diff --git a/docs/reference/pip_hash.rst b/docs/reference/pip_hash.rst
@@ -3,8 +3,6 @@
 pip hash
 ------------
 
-.. contents::
-
 Usage
 *****
 

diff --git a/docs/reference/pip_install.rst b/docs/reference/pip_install.rst
@@ -3,8 +3,6 @@
 pip install
 -----------
 
-.. contents::
-
 Usage
 *****
 

diff --git a/docs/reference/pip_list.rst b/docs/reference/pip_list.rst
@@ -3,8 +3,6 @@
 pip list
 ---------
 
-.. contents::
-
 Usage
 *****
 

diff --git a/docs/reference/pip_search.rst b/docs/reference/pip_search.rst
@@ -3,8 +3,6 @@
 pip search
 ----------
 
-.. contents::
-
 Usage
 *****
 

diff --git a/docs/reference/pip_show.rst b/docs/reference/pip_show.rst
@@ -3,9 +3,6 @@
 pip show
 --------
 
-.. contents::
-
-
 Usage
 *****
 

diff --git a/docs/reference/pip_uninstall.rst b/docs/reference/pip_uninstall.rst
@@ -3,8 +3,6 @@
 pip uninstall
 -------------
 
-.. contents::
-
 Usage
 *****
 

diff --git a/docs/reference/pip_wheel.rst b/docs/reference/pip_wheel.rst
@@ -4,8 +4,6 @@
 pip wheel
 ---------
 
-.. contents::
-
 Usage
 *****
 

diff --git a/docs/user_guide.rst b/docs/user_guide.rst
@@ -2,8 +2,6 @@
 User Guide
 ==========
 
-.. contents::
-
 Running pip
 ***********
 

diff --git a/news/4758.feature b/news/4758.feature
@@ -0,0 +1 @@
+Change documentation theme to be in line with Python Documentation
diff --git a/tox.ini b/tox.ini
@@ -13,11 +13,15 @@ commands = py.test --timeout 300 []
 install_command = python -m pip install {opts} {packages}
 
 [testenv:docs]
-deps = sphinx == 1.6.1
+deps =
+    sphinx == 1.6.1
+    git+https://github.com/python/python-docs-theme.git#egg=python-docs-theme
+    git+https://github.com/pypa/pypa-docs-theme.git#egg=pypa-docs-theme
+
 basepython = python2.7
 commands =
-    sphinx-build -W -b html -d {envtmpdir}/doctrees docs docs/_build/html
-    sphinx-build -W -b man -d {envtmpdir}/doctrees docs docs/_build/man
+    sphinx-build -W -b html -d {envtmpdir}/doctrees docs docs/build/html
+    sphinx-build -W -b man -d {envtmpdir}/doctrees docs docs/build/man
 
 [testenv:packaging]
 deps =