From 8f6b4c9b2d014b9a646585074612cecf51e1cc88 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 12 Nov 2017 21:34:37 +0530 Subject: [PATCH] Navigation (+other) improvements to Documentation (#4855) --- MANIFEST.in | 3 +++ docs-requirements.txt | 2 +- docs/conf.py | 2 +- docs/docutils.conf | 2 ++ docs/pipext.py | 8 ++++---- docs/reference/index.rst | 2 +- docs/reference/pip.rst | 2 ++ docs/reference/pip_check.rst | 2 ++ docs/reference/pip_config.rst | 2 ++ docs/reference/pip_download.rst | 2 ++ docs/reference/pip_freeze.rst | 2 ++ docs/reference/pip_hash.rst | 2 ++ docs/reference/pip_install.rst | 2 ++ docs/reference/pip_list.rst | 2 ++ docs/reference/pip_search.rst | 2 ++ docs/reference/pip_show.rst | 3 +++ docs/reference/pip_uninstall.rst | 2 ++ docs/reference/pip_wheel.rst | 2 ++ docs/user_guide.rst | 2 ++ 19 files changed, 39 insertions(+), 7 deletions(-) create mode 100644 docs/docutils.conf diff --git a/MANIFEST.in b/MANIFEST.in index 01f54592215..fa58d7a89bf 100644 --- 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 index 9bdbf1b3cd2..86c5258b1e0 100644 --- 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 index 74d73b39ddd..08f31e61b51 100644 --- 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 new file mode 100644 index 00000000000..dfd80b177a8 --- /dev/null +++ b/docs/docutils.conf @@ -0,0 +1,2 @@ +[restructuredtext parser] +smart_quotes = no diff --git a/docs/pipext.py b/docs/pipext.py index 39ee3413daf..c866e1d717d 100644 --- a/docs/pipext.py +++ b/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] diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 6308919de64..f25568bfb15 100644 --- 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 index df312eccd42..c5a1201f581 100644 --- 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 index 5663335d232..2c33e90a3ec 100644 --- 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 index baab537eaec..0f92f5714a7 100644 --- 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 index ff65fa03906..d5c654821b4 100644 --- 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 index 80986249891..c13bc00f3b6 100644 --- 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 index 71e325a7278..72052bc22dc 100644 --- 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 index a1fba2c2638..b86e78eea7f 100644 --- 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 index 469305f665a..c459b7a3bb1 100644 --- 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 index 11c0fb168be..1332c99f781 100644 --- 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 index ada91f89bc1..6c9aa84aae4 100644 --- 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 index 954cb659338..f9a97589eb5 100644 --- 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 index 0b360e31288..75ae51a21fb 100644 --- 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 index 7e7db638930..052a7cda11e 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -2,6 +2,8 @@ User Guide ========== +.. contents:: + Running pip ***********