WIP upd directive to use cmd prefix + upd ref docs

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,22 +90,41 @@ 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 \
+      .. 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 \
+      .. group-tab:: Unix/macOS
+
+        .. code-block:: shell
+
+          $ python -m pip download \
               --only-binary=:all: \
               --platform linux_x86_64 \
               --python-version 3 \
@@ -92,11 +132,27 @@ Examples
               --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 \
+      .. group-tab:: Unix/macOS
+
+        .. code-block:: shell
+
+          $ python -m pip download \
               --only-binary=:all: \
               --platform any \
               --python-version 3 \
@@ -104,16 +160,48 @@ Examples
               --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 \
+      .. 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

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,9 +39,24 @@ Examples
 
 #. Generate output suitable for a requirements file.
 
-    ::
+    .. tabs::
 
-     $ pip freeze
+      .. 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
@@ -43,7 +66,18 @@ Examples
 
 #. Generate a requirements file and then install from it in another environment.
 
-    ::
+    .. tabs::
 
-     $ env1/bin/pip freeze > requirements.txt
+      .. group-tab:: Unix/macOS
-     $ env2/bin/pip install -r requirements.txt
+
+        .. 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

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"
 
 
 

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,9 +38,24 @@ Examples
 
 #. Uninstall a package.
 
-  ::
+  .. tabs::
 
-    $ pip uninstall 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

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]