Merge pull request #2194 from yuvipanda/pip-cleanup

Use python3 -m pip explicitly in docs

docs/source/contributing/docs.rst

@@ -10,7 +10,6 @@ you get set up on how to contribute documentation to JupyterHub.
 Building documentation locally
 ==============================
 
-
 We use `sphinx <http://sphinx-doc.org>`_ to build our documentation. It takes
 our documentation source files (written in `markdown
 <https://daringfireball.net/projects/markdown/>`_ or `reStructuredText
@@ -25,7 +24,7 @@ change renders correctly, it is good practice to test it locally.
 
    .. code-block:: bash
 
-      pip install -r docs/requirements.txt
+      python3 -m pip install -r docs/requirements.txt
 
 #. Build the html version of the docs. This is the most commonly used
    output format, so verifying it renders as you should is usually good
@@ -47,3 +46,34 @@ change renders correctly, it is good practice to test it locally.
 
       On macOS, you can open a file from the terminal with ``open <path-to-file>``.
       On Linux, you can do the same with ``xdg-open <path-to-file>``.
+
+
+.. _contributing/docs/conventions:
+
+Documentation conventions
+=========================
+
+This section lists various conventions we use in our documentation. This is a
+living document that grows over time, so feel free to add to it / change it!
+
+Our entire documentation does not yet fully conform to these conventions yet,
+so help in making it so would be appreciated!
+
+``pip`` invocations
+-------------------
+
+There are three ways to invoke a ``pip`` command:
+
+1. ``pip``
+    This points to python3 pip if you are in an appropriate environment,
+    but in some cases it can actually point to a python2 pip.
+
+2. ``pip3``
+   When present, this always points to a python3 pip, most likely in
+   the same environment as your python3.
+
+3. ``python3 -m pip``
+   This invokes pip explicitly using the python3 binary that you are
+   currently using. This is the **recommended way** to invoke pip
+   in our documentation, since it is least likely to cause problems
+   with python3 and pip being from different environments.

docs/source/contributing/setup.rst

@@ -90,8 +90,8 @@ happen.
 
    .. code:: bash
 
-      pip3 install -r dev-requirements.txt
-      pip3 install -r requirements.txt
+      python3 -m pip install -r dev-requirements.txt
+      python3 -m pip install -r requirements.txt
 
 5. Install the development version of JupyterHub. This lets you edit
    JupyterHub code in a text editor & restart the JupyterHub process to
@@ -99,7 +99,7 @@ happen.
 
    .. code:: bash
 
-      pip3 install --editable .
+      python3 -m pip install --editable .
 
 6. You are now ready to start JupyterHub!
 
@@ -158,7 +158,7 @@ another way it can fail!
 ``lessc`` not found
 -------------------
 
-If the ``pip3 install --editable .`` command fails and complains about
+If the ``python3 -m pip install --editable .`` command fails and complains about
 ``lessc`` being unavailable, you may need to explicitly install some
 additional JavaScript dependencies:
 

docs/source/reference/config-sudo.md

@@ -37,7 +37,7 @@ Next, you will need [sudospawner](https://github.com/jupyter/sudospawner)
 to enable monitoring the single-user servers with sudo:
 
 ```bash
-sudo pip install sudospawner
+sudo python3 -m pip install sudospawner
 ```
 
 Now we have to configure sudo to allow the Hub user (`rhea`) to launch

docs/source/reference/upgrading.md

@@ -74,7 +74,7 @@ Next, shutdown the JupyterHub service.
 
 Follow directions that correspond to your package manager, `pip` or `conda`,
 for the new JupyterHub release. These directions will guide you to the
-specific command. In general, `pip install -U jupyterhub` or
+specific command. In general, `python3 -m pip install -U jupyterhub` or
 `conda upgrade jupyterhub`
 
 ### Upgrade JupyterHub databases
@@ -93,6 +93,6 @@ jupyterhub upgrade-db
 2. Backup JupyterHub configuration file: `jupyterhub_config.py`
 3. Shutdown the Hub
 4. Upgrade JupyterHub
-    - `pip install -U jupyterhub` when using `pip`
+    - `python3 -m pip install -U jupyterhub` when using `pip`
     - `conda upgrade jupyterhub` when using `conda`
 5. Upgrade the database using run `jupyterhub upgrade-db`

docs/source/troubleshooting.md

@@ -204,7 +204,7 @@ from there instead of the internet.
 For instance, you can install JupyterHub with pip and configurable-http-proxy
 with npmbox:
 
-    pip wheel jupyterhub
+    python3 -m pip wheel jupyterhub
     npmbox configurable-http-proxy
 
 ### I want access to the whole filesystem, but still default users to their home directory
@@ -236,7 +236,7 @@ then you can change the default URL to `/lab`.
 
 For instance:
 
-    pip install jupyterlab
+    python3 -m pip install jupyterlab
     jupyter serverextension enable --py jupyterlab --sys-prefix
 
 The important thing is that jupyterlab is installed and enabled in the

docs/source/tutorials/upgrade-dot-eight.rst

@@ -17,7 +17,7 @@ Upgrade checklist
 2. Backup the existing JupyterHub configuration file: ``jupyterhub_config.py``
 3. Shutdown the Hub
 4. Upgrade JupyterHub
-    - ``pip install -U jupyterhub`` when using ``pip``
+    - ``python3 -m pip install -U jupyterhub`` when using ``pip``
     - ``conda upgrade jupyterhub`` when using ``conda``
 5. Upgrade the database using run ```jupyterhub upgrade-db``
 6. Update the JupyterHub configuration file ``jupyterhub_config.py``
@@ -69,7 +69,7 @@ Upgrade JupyterHub
 Follow directions that correspond to your package manager, ``pip`` or ``conda``,
 for the new JupyterHub release:
 
-- ``pip install -U jupyterhub`` for ``pip``
+- ``python3 -m pip install -U jupyterhub`` for ``pip``
 - ``conda upgrade jupyterhub`` for ``conda``
 
 Upgrade the proxy, authenticator, or spawner if needed.