From 7c273296c2c92bf0314d880ab3ca068691b04320 Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Wed, 26 Sep 2018 12:11:29 -0700 Subject: [PATCH] Use python3 -m pip explicitly in docs - Add a documentation convention listing this too. Fixes #2191 --- docs/source/contributing/docs.rst | 36 +++++++++++++++++++-- docs/source/contributing/setup.rst | 8 ++--- docs/source/reference/config-sudo.md | 2 +- docs/source/reference/upgrading.md | 4 +-- docs/source/troubleshooting.md | 4 +-- docs/source/tutorials/upgrade-dot-eight.rst | 4 +-- 6 files changed, 44 insertions(+), 14 deletions(-) diff --git a/docs/source/contributing/docs.rst b/docs/source/contributing/docs.rst index 42637c8a..b1dceb37 100644 --- a/docs/source/contributing/docs.rst +++ b/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 `_ to build our documentation. It takes our documentation source files (written in `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 @@ -46,4 +45,35 @@ change renders correctly, it is good practice to test it locally. .. tip:: On macOS, you can open a file from the terminal with ``open ``. - On Linux, you can do the same with ``xdg-open ``. \ No newline at end of file + On Linux, you can do the same with ``xdg-open ``. + + +.. _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. \ No newline at end of file diff --git a/docs/source/contributing/setup.rst b/docs/source/contributing/setup.rst index cb949def..159441be 100644 --- a/docs/source/contributing/setup.rst +++ b/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: diff --git a/docs/source/reference/config-sudo.md b/docs/source/reference/config-sudo.md index aad24e37..2a9e115b 100644 --- a/docs/source/reference/config-sudo.md +++ b/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 diff --git a/docs/source/reference/upgrading.md b/docs/source/reference/upgrading.md index d4e2b7a2..2ec094e1 100644 --- a/docs/source/reference/upgrading.md +++ b/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` diff --git a/docs/source/troubleshooting.md b/docs/source/troubleshooting.md index 8f1ac382..270a26de 100644 --- a/docs/source/troubleshooting.md +++ b/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 diff --git a/docs/source/tutorials/upgrade-dot-eight.rst b/docs/source/tutorials/upgrade-dot-eight.rst index 8945c63b..0d902854 100644 --- a/docs/source/tutorials/upgrade-dot-eight.rst +++ b/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.