Repository: pypa/pip

Issue:
Use python -m to run pip.
It's recommend to use python -m with pip. See this article:

https://snarky.ca/why-you-should-use-python-m-pip/

It can be to add a new documentation about that and change the examples in the documentation to use this way.


Discussion:
See also https://github.com/pypa/warehouse/issues/1563. 

And possibly a duplicate of https://github.com/pypa/pip/issues/3164. 
I think this is just referring to updating our documentation, which would be part of the activities needed to deprecate but could also be done on its own.
Sorry I'm not sure to understand what you mean.
Can I take up this issue ?
@sagnik-chatterjee I think you can
Hello - If nobody is looking into this, can I take a crack at it?
@shireenrao Go for it! 
Should I submit changes a page at a time on a single PR? Get it approved and then push the next page changes or should I change all the pages at once?
If it’s all just replacing `pip` with `python -m pip`, I’d say you can do multiple at a time. The general guide line on splitting pull requests is to keep things logically separated, not quantatively.
Check the docs, for example:

> Pull requests should be small to facilitate easier review. Keep them self-contained, and limited in scope.

https://pip.pypa.io/en/stable/development/contributing/#submitting-pull-requests

I'm not a maintainer here, but I'd suggest to put them all in a single PR unless you feel it's much too big. You can always split later.

Resolving patch:
diff --git a/docs/html/conf.py b/docs/html/conf.py
--- a/docs/html/conf.py
+++ b/docs/html/conf.py
@@ -30,7 +30,12 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 # extensions = ['sphinx.ext.autodoc']
-extensions = ['sphinx.ext.extlinks', 'pip_sphinxext', 'sphinx.ext.intersphinx']
+extensions = [
+    'sphinx.ext.extlinks',
+    'pip_sphinxext',
+    'sphinx.ext.intersphinx',
+    'sphinx_tabs.tabs',
+]
 
 # intersphinx
 intersphinx_cache_limit = 0
@@ -130,6 +135,9 @@
     'pypi': ('https://pypi.org/project/%s/', ''),
 }
 
+# Turn off sphinx build warnings because of sphinx tabs during man pages build
+sphinx_tabs_nowarn = True
+
 # -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
diff --git a/docs/pip_sphinxext.py b/docs/pip_sphinxext.py
--- a/docs/pip_sphinxext.py
+++ b/docs/pip_sphinxext.py
@@ -15,11 +15,17 @@
 
 class PipCommandUsage(rst.Directive):
     required_arguments = 1
+    optional_arguments = 3
 
     def run(self):
         cmd = create_command(self.arguments[0])
+        cmd_prefix = 'python -m pip'
+        if len(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', 'pip {}'.format(cmd.name))
+            cmd.usage.replace('%prog', '{} {}'.format(cmd_prefix, cmd.name))
         ).strip()
         node = nodes.literal_block(usage, usage)
         return [node]


Test patch: