Navigation (+other) improvements to Documentation (#4855)

MANIFEST.in

@@ -3,9 +3,12 @@ include LICENSE.txt
 include NEWS.rst
 include README.rst
 include pyproject.toml
+
 include src/pip/_vendor/README.rst
 include src/pip/_vendor/vendor.txt
 
+include docs/docutils.conf
+
 exclude .coveragerc
 exclude .mailmap
 exclude .travis.yml

docs-requirements.txt

@@ -1,4 +1,4 @@
-sphinx == 1.6.1
+sphinx == 1.6.*
 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
 

docs/conf.py

@@ -127,7 +127,7 @@ html_theme = "pypa_theme"
 html_theme_options = {
     'collapsiblesidebar': True,
     'externalrefs': True,
-    'navigation_depth': 2,
+    'navigation_depth': 3,
     'issues_url': 'https://github.com/pypa/pip/issues'
 }
 

docs/docutils.conf

@@ -0,0 +1,2 @@
+[restructuredtext parser]
+smart_quotes = no

docs/pipext.py

@@ -2,13 +2,14 @@
 
 import optparse
 import sys
+from textwrap import dedent
+
 from docutils import nodes
 from docutils.parsers import rst
 from docutils.statemachine import ViewList
-from textwrap import dedent
+
 from pip._internal import cmdoptions
 from pip._internal.commands import commands_dict as commands
-from pip._internal.utils.misc import get_prog
 
 
 class PipCommandUsage(rst.Directive):
@@ -16,8 +17,7 @@ class PipCommandUsage(rst.Directive):
 
     def run(self):
         cmd = commands[self.arguments[0]]
-        prog = '%s %s' % (get_prog(), cmd.name)
-        usage = dedent(cmd.usage.replace('%prog', prog)).strip()
+        usage = dedent(cmd.usage.replace('%prog', 'pip')).strip()
         node = nodes.literal_block(usage, usage)
         return [node]
 

docs/reference/index.rst

@@ -3,7 +3,7 @@ Reference Guide
 ===============
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    pip
    pip_install

docs/reference/pip.rst

@@ -1,6 +1,8 @@
 pip
 ---
 
+.. contents::
+
 Usage
 *****
 

docs/reference/pip_check.rst

@@ -3,6 +3,8 @@
 pip check
 ---------
 
+.. contents::
+
 Usage
 *****
 

docs/reference/pip_config.rst

@@ -4,6 +4,8 @@
 pip config
 ------------
 
+.. contents::
+
 Usage
 *****
 

docs/reference/pip_download.rst

@@ -4,6 +4,8 @@
 pip download
 ------------
 
+.. contents::
+
 Usage
 *****
 

docs/reference/pip_freeze.rst

@@ -4,6 +4,8 @@
 pip freeze
 -----------
 
+.. contents::
+
 Usage
 *****
 

docs/reference/pip_hash.rst

@@ -3,6 +3,8 @@
 pip hash
 ------------
 
+.. contents::
+
 Usage
 *****
 

docs/reference/pip_install.rst

@@ -3,6 +3,8 @@
 pip install
 -----------
 
+.. contents::
+
 Usage
 *****
 

docs/reference/pip_list.rst

@@ -3,6 +3,8 @@
 pip list
 ---------
 
+.. contents::
+
 Usage
 *****
 

docs/reference/pip_search.rst

@@ -3,6 +3,8 @@
 pip search
 ----------
 
+.. contents::
+
 Usage
 *****
 

docs/reference/pip_show.rst

@@ -3,6 +3,9 @@
 pip show
 --------
 
+.. contents::
+
+
 Usage
 *****
 

docs/reference/pip_uninstall.rst

@@ -3,6 +3,8 @@
 pip uninstall
 -------------
 
+.. contents::
+
 Usage
 *****
 

docs/reference/pip_wheel.rst

@@ -4,6 +4,8 @@
 pip wheel
 ---------
 
+.. contents::
+
 Usage
 *****
 

docs/user_guide.rst

@@ -2,6 +2,8 @@
 User Guide
 ==========
 
+.. contents::
+
 Running pip
 ***********