From 423ccfd4f13e43fb0bdee16ee0220e95813ff45f Mon Sep 17 00:00:00 2001 From: Srinivas Nyayapati Date: Wed, 5 Aug 2020 23:18:37 -0400 Subject: [PATCH] WIP upd directive to use cmd prefix + upd ref docs --- docs/html/reference/pip_download.rst | 164 ++++++++++++++++++++------ docs/html/reference/pip_freeze.rst | 56 +++++++-- docs/html/reference/pip_install.rst | 4 +- docs/html/reference/pip_uninstall.rst | 39 ++++-- docs/pip_sphinxext.py | 10 +- 5 files changed, 210 insertions(+), 63 deletions(-) diff --git a/docs/html/reference/pip_download.rst b/docs/html/reference/pip_download.rst index b74b1d240..d3c217b94 100644 --- a/docs/html/reference/pip_download.rst +++ b/docs/html/reference/pip_download.rst @@ -11,7 +11,15 @@ pip download Usage ===== -.. pip-command-usage:: download +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: download "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: download "py -m pip" Description @@ -56,11 +64,24 @@ Examples #. Download a package and all of its dependencies - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip download SomePackage + $ python -m pip download -d . SomePackage # equivalent to above + $ python -m pip download --no-index --find-links=/tmp/wheelhouse -d /tmp/otherwheelhouse SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip download SomePackage + C:\> py -m pip download -d . SomePackage # equivalent to above + C:\> py -m pip download --no-index --find-links=/tmp/wheelhouse -d /tmp/otherwheelhouse SomePackage - $ pip download SomePackage - $ pip download -d . SomePackage # equivalent to above - $ pip download --no-index --find-links=/tmp/wheelhouse -d /tmp/otherwheelhouse SomePackage #. Download a package and all of its dependencies with OSX specific interpreter constraints. This forces OSX 10.10 or lower compatibility. Since OSX deps are forward compatible, @@ -69,51 +90,118 @@ Examples It will also match deps with platform ``any``. Also force the interpreter version to ``27`` (or more generic, i.e. ``2``) and implementation to ``cp`` (or more generic, i.e. ``py``). - :: + .. tabs:: - $ pip download \ - --only-binary=:all: \ - --platform macosx-10_10_x86_64 \ - --python-version 27 \ - --implementation cp \ - SomePackage + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip download \ + --only-binary=:all: \ + --platform macosx-10_10_x86_64 \ + --python-version 27 \ + --implementation cp \ + SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip download ^ + --only-binary=:all: ^ + --platform macosx-10_10_x86_64 ^ + --python-version 27 ^ + --implementation cp ^ + SomePackage #. Download a package and its dependencies with linux specific constraints. Force the interpreter to be any minor version of py3k, and only accept ``cp34m`` or ``none`` as the abi. - :: + .. tabs:: - $ pip download \ - --only-binary=:all: \ - --platform linux_x86_64 \ - --python-version 3 \ - --implementation cp \ - --abi cp34m \ - SomePackage + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip download \ + --only-binary=:all: \ + --platform linux_x86_64 \ + --python-version 3 \ + --implementation cp \ + --abi cp34m \ + SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip download ^ + --only-binary=:all: ^ + --platform linux_x86_64 ^ + --python-version 3 ^ + --implementation cp ^ + --abi cp34m ^ + SomePackage #. Force platform, implementation, and abi agnostic deps. - :: + .. tabs:: - $ pip download \ - --only-binary=:all: \ - --platform any \ - --python-version 3 \ - --implementation py \ - --abi none \ - SomePackage + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip download \ + --only-binary=:all: \ + --platform any \ + --python-version 3 \ + --implementation py \ + --abi none \ + SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip download ^ + --only-binary=:all: ^ + --platform any ^ + --python-version 3 ^ + --implementation py ^ + --abi none ^ + SomePackage #. Even when overconstrained, this will still correctly fetch the pip universal wheel. - :: + .. tabs:: - $ pip download \ - --only-binary=:all: \ - --platform linux_x86_64 \ - --python-version 33 \ - --implementation cp \ - --abi cp34m \ - pip>=8 - $ ls pip-8.1.1-py2.py3-none-any.whl - pip-8.1.1-py2.py3-none-any.whl + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip download \ + --only-binary=:all: \ + --platform linux_x86_64 \ + --python-version 33 \ + --implementation cp \ + --abi cp34m \ + pip>=8 + + $ ls pip-8.1.1-py2.py3-none-any.whl + pip-8.1.1-py2.py3-none-any.whl + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip download ^ + --only-binary=:all: ^ + --platform linux_x86_64 ^ + --python-version 33 ^ + --implementation cp ^ + --abi cp34m ^ + pip>=8 + + C:\> dir pip-8.1.1-py2.py3-none-any.whl + pip-8.1.1-py2.py3-none-any.whl diff --git a/docs/html/reference/pip_freeze.rst b/docs/html/reference/pip_freeze.rst index 31efd571b..cd180e095 100644 --- a/docs/html/reference/pip_freeze.rst +++ b/docs/html/reference/pip_freeze.rst @@ -11,7 +11,15 @@ pip freeze Usage ===== -.. pip-command-usage:: freeze +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: freeze "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: freeze "py -m pip" Description @@ -31,19 +39,45 @@ Examples #. Generate output suitable for a requirements file. - :: + .. tabs:: - $ pip freeze - docutils==0.11 - Jinja2==2.7.2 - MarkupSafe==0.19 - Pygments==1.6 - Sphinx==1.2.2 + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip freeze + docutils==0.11 + Jinja2==2.7.2 + MarkupSafe==0.19 + Pygments==1.6 + Sphinx==1.2.2 + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip freeze + docutils==0.11 + Jinja2==2.7.2 + MarkupSafe==0.19 + Pygments==1.6 + Sphinx==1.2.2 #. Generate a requirements file and then install from it in another environment. - :: + .. tabs:: - $ env1/bin/pip freeze > requirements.txt - $ env2/bin/pip install -r requirements.txt + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ env1/bin/python -m pip freeze > requirements.txt + $ env2/bin/python -m pip install -r requirements.txt + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> env1\bin\python -m pip freeze > requirements.txt + C:\> env2\bin\python -m pip install -r requirements.txt diff --git a/docs/html/reference/pip_install.rst b/docs/html/reference/pip_install.rst index 69ea76275..67cfd03c6 100644 --- a/docs/html/reference/pip_install.rst +++ b/docs/html/reference/pip_install.rst @@ -14,11 +14,11 @@ Usage .. group-tab:: Unix/macOS - .. pip-command-usage:: install $ python -m pip + .. pip-command-usage:: install "python -m pip" .. group-tab:: Windows - .. pip-command-usage:: install C:\> py -m pip + .. pip-command-usage:: install "py -m pip" diff --git a/docs/html/reference/pip_uninstall.rst b/docs/html/reference/pip_uninstall.rst index 67d752d6b..165ac4cd5 100644 --- a/docs/html/reference/pip_uninstall.rst +++ b/docs/html/reference/pip_uninstall.rst @@ -10,7 +10,15 @@ pip uninstall Usage ===== -.. pip-command-usage:: uninstall +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: uninstall "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: uninstall "py -m pip" Description @@ -30,11 +38,26 @@ Examples #. Uninstall a package. - :: + .. tabs:: - $ pip uninstall simplejson - Uninstalling simplejson: - /home/me/env/lib/python2.7/site-packages/simplejson - /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info - Proceed (y/n)? y - Successfully uninstalled simplejson + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip uninstall simplejson + Uninstalling simplejson: + /home/me/env/lib/python2.7/site-packages/simplejson + /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info + Proceed (y/n)? y + Successfully uninstalled simplejson + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip uninstall simplejson + Uninstalling simplejson: + /home/me/env/lib/python2.7/site-packages/simplejson + /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info + Proceed (y/n)? y + Successfully uninstalled simplejson diff --git a/docs/pip_sphinxext.py b/docs/pip_sphinxext.py index 0e7571eea..9386d71e7 100644 --- a/docs/pip_sphinxext.py +++ b/docs/pip_sphinxext.py @@ -15,15 +15,17 @@ from pip._internal.req.req_file import SUPPORTED_OPTIONS class PipCommandUsage(rst.Directive): required_arguments = 1 - optional_arguments = 4 + optional_arguments = 3 def run(self): cmd = create_command(self.arguments[0]) - pip_cmd = '$ python -m pip' + cmd_prefix = 'python -m pip' if len(self.arguments) > 1: - pip_cmd = " ".join(self.arguments[1:]) + cmd_prefix = " ".join(self.arguments[1:]) + cmd_prefix = cmd_prefix.strip('"') + cmd_prefix = cmd_prefix.strip("'") usage = dedent( - cmd.usage.replace('%prog', '{} {}'.format(pip_cmd, cmd.name)) + cmd.usage.replace('%prog', '{} {}'.format(cmd_prefix, cmd.name)) ).strip() node = nodes.literal_block(usage, usage) return [node]