docs: Use pip best practices with python -m pip (#730)

* Use pip best practices in the docs by using 'python -m pip'

Author: matthewfeickert

.readthedocs.yml

@@ -12,7 +12,7 @@ sphinx:
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: all
 
-# pip install .[docs]
+# python -m pip install .[docs]
 python:
   version: 3.7
   install:

README.md

@@ -96,18 +96,18 @@ bin 2: nobs = 145, b = 150, db = 20., nom_sig = 45.
 
 To install `pyhf` from PyPI with the NumPy backend run
 ```bash
-pip install pyhf
+python -m pip install pyhf
 ```
 
-and to install `pyhf` with additional backends run
+and to install `pyhf` with all additional backends run
 ```bash
-pip install pyhf[tensorflow,torch]
+python -m pip install pyhf[backends]
 ```
 or a subset of the options.
 
 To uninstall run
 ```bash
-pip uninstall pyhf
+python -m pip uninstall pyhf
 ```
 
 ## Authors

docs/development.rst

@@ -11,7 +11,7 @@ and install all necessary packages for development
 
 .. code-block:: console
 
-    pip install --ignore-installed -U -e .[complete]
+    python -m pip install --ignore-installed -U -e .[complete]
 
 Then setup the Git pre-commit hook for `Black <https://github.com/psf/black>`__  by running
 

docs/examples/notebooks/XML_ImportExport.ipynb

@@ -13,7 +13,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# NB: pip install pyhf[xmlio]\n",
+    "# NB: python -m pip install pyhf[xmlio]\n",
     "import pyhf"
    ]
   },

docs/installation.rst

@@ -29,43 +29,43 @@ Install latest stable release from `PyPI <https://pypi.org/project/pyhf/>`__...
 
 .. code-block:: console
 
-    pip install pyhf
+    python -m pip install pyhf
 
 ... with TensorFlow backend
 +++++++++++++++++++++++++++
 
 .. code-block:: console
 
-    pip install pyhf[tensorflow]
+    python -m pip install pyhf[tensorflow]
 
 ... with PyTorch backend
 ++++++++++++++++++++++++
 
 .. code-block:: console
 
-    pip install pyhf[torch]
+    python -m pip install pyhf[torch]
 
 ... with JAX backend
 ++++++++++++++++++++
 
 .. code-block:: console
 
-    pip install pyhf[jax]
+    python -m pip install pyhf[jax]
 
 ... with all backends
 +++++++++++++++++++++
 
 .. code-block:: console
 
-    pip install pyhf[backends]
+    python -m pip install pyhf[backends]
 
 
 ... with xml import/export functionality
 ++++++++++++++++++++++++++++++++++++++++
 
 .. code-block:: console
 
-    pip install pyhf[xmlio]
+    python -m pip install pyhf[xmlio]
 
 
 Install latest development version from `GitHub <https://github.com/scikit-hep/pyhf>`__...
@@ -76,43 +76,43 @@ Install latest development version from `GitHub <https://github.com/scikit-hep/p
 
 .. code-block:: console
 
-    pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf"
+    python -m pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf"
 
 ... with TensorFlow backend
 +++++++++++++++++++++++++++
 
 .. code-block:: console
 
-    pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[tensorflow]"
+    python -m pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[tensorflow]"
 
 ... with PyTorch backend
 ++++++++++++++++++++++++
 
 .. code-block:: console
 
-    pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[torch]"
+    python -m pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[torch]"
 
 ... with JAX backend
 ++++++++++++++++++++++
 
 .. code-block:: console
 
-    pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[jax]"
+    python -m pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[jax]"
 
 ... with all backends
 +++++++++++++++++++++
 
 .. code-block:: console
 
-    pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[backends]"
+    python -m pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[backends]"
 
 
 ... with xml import/export functionality
 ++++++++++++++++++++++++++++++++++++++++
 
 .. code-block:: console
 
-    pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[xmlio]"
+    python -m pip install --ignore-installed -U "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[xmlio]"
 
 
 Updating :code:`pyhf`

src/pyhf/cli/rootio.py

@@ -45,7 +45,7 @@ def xml2json(entrypoint_xml, basedir, output_file, track_progress):
     except ImportError:
         log.error(
             "xml2json requires uproot, please install pyhf using the "
-            "xmlio extra: pip install pyhf[xmlio]"
+            "xmlio extra: python -m pip install pyhf[xmlio]"
         )
     from .. import readxml
 
@@ -73,7 +73,7 @@ def json2xml(workspace, output_dir, specroot, dataroot, resultprefix, patch):
     except ImportError:
         log.error(
             "json2xml requires uproot, please install pyhf using the "
-            "xmlio extra: pip install pyhf[xmlio]"
+            "xmlio extra: python -m pip install pyhf[xmlio]"
         )
     from .. import writexml