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

pypa · Nov 12, 2017 · 8f6b4c9 · 8f6b4c9
1 parent 3651dd8
commit 8f6b4c9
Show file tree

Hide file tree

Showing 19 changed files with 39 additions and 7 deletions.
diff --git a/MANIFEST.in b/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

diff --git a/docs-requirements.txt b/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
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -127,7 +127,7 @@
 html_theme_options = {
     'collapsiblesidebar': True,
     'externalrefs': True,
-    'navigation_depth': 2,
+    'navigation_depth': 3,
     'issues_url': 'https://github.com/pypa/pip/issues'
 }
 

diff --git a/docs/docutils.conf b/docs/docutils.conf
@@ -0,0 +1,2 @@
+[restructuredtext parser]
+smart_quotes = no
diff --git a/docs/pipext.py b/docs/pipext.py
@@ -2,22 +2,22 @@
 
 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):
     required_arguments = 1
 
     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]
 

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

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

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

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

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

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

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

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

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

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

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

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

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

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