Docs: python3 -m pip & Virtual Env (#2656)

ax3l · web-flow · commit 3526de29709e · 2021-12-10T08:24:38.000-08:00
* Docs: `python3 -m pip` Use `python3 -m pip`: - works independent of PATH - always uses the right Python - is the recommended way to use `pip` * Dependencies: Python incl. venv Backported from #2556. Follow-up to #2653
diff --git a/Docs/README.md b/Docs/README.md
@@ -8,7 +8,7 @@ This explains how to generate the documentation for Warpx, and contribute to it.
 
 Install the Python requirements for compiling the documentation:
 ```
-pip install sphinx sphinx_rtd_theme
+python3 -m pip install sphinx sphinx_rtd_theme
 ```
 
 ### Compiling the documentation
diff --git a/Docs/source/dataanalysis/openpmdviewer.rst b/Docs/source/dataanalysis/openpmdviewer.rst
@@ -21,7 +21,7 @@ openPMD-viewer can be installed via ``conda`` or ``pip``:
 
 .. code-block:: bash
 
-    pip install openPMD-viewer openPMD-api
+    python3 -m pip install openPMD-viewer openPMD-api
 
 Usage
 -----
diff --git a/Docs/source/dataanalysis/picviewer.rst b/Docs/source/dataanalysis/picviewer.rst
@@ -43,7 +43,7 @@ Required software
 
   ::
 
-    pip install git+https://github.com/yt-project/yt.git --user
+    python3 -m pip install git+https://github.com/yt-project/yt.git --user
 
 * numba
 
@@ -53,15 +53,15 @@ Installation
 
 ::
 
-  pip install picviewer
+  python3 -m pip install picviewer
 
 You need to install yt and PySide separately.
 
 You can install from the source for the latest update,
 
 ::
 
-  pip install git+https://bitbucket.org/ecp_warpx/picviewer/
+  python3 -m pip install git+https://bitbucket.org/ecp_warpx/picviewer/
 
 
 To install manually
diff --git a/Docs/source/dataanalysis/yt.rst b/Docs/source/dataanalysis/yt.rst
@@ -19,8 +19,8 @@ From the terminal, install the latest version of yt:
 
 .. code-block:: bash
 
-    pip install cython
-    python -m pip install --upgrade yt
+    python3 -m pip install cython
+    python3 -m pip install --upgrade yt
 
 Alternatively, yt can be installed via their installation script, see `yt installation web page <https://yt-project.org/doc/installing.html>`__.
 
diff --git a/Docs/source/developers/documentation.rst b/Docs/source/developers/documentation.rst
@@ -55,7 +55,7 @@ First, change into ``Docs/`` and install the Python requirements:
 .. code-block:: sh
 
     cd Docs/
-    pip install -r requirements.txt
+    python3 -m pip install -r requirements.txt
 
 You will also need Doxygen (macOS: ``brew install doxygen``; Ubuntu: ``sudo apt install doxygen``).
 
diff --git a/Docs/source/developers/testing.rst b/Docs/source/developers/testing.rst
@@ -77,8 +77,9 @@ Add a test to the suite
 There are three steps to follow to add a new automated test (illustrated here for PML boundary conditions):
 
 * An input file for your test, in folder `Example/Tests/...`. For the PML test, the input file is at ``Examples/Tests/PML/inputs_2d``. You can also re-use an existing input file (even better!) and pass specific parameters at runtime (see below).
-* A Python script that reads simulation output and tests correctness versus theory or calibrated results. For the PML test, see ``Examples/Tests/PML/analysis_pml_yee.py``. It typically ends with Python statement `assert( error<0.01 )`.
-* Add an entry to [Regression/WarpX-tests.ini](./Regression/WarpX-tests.ini), so that a WarpX simulation runs your test in the continuous integration process, and the Python script is executed to assess the correctness. For the PML test, the entry is
+* A Python script that reads simulation output and tests correctness versus theory or calibrated results. For the PML test, see ``Examples/Tests/PML/analysis_pml_yee.py``. It typically ends with Python statement ``assert( error<0.01 )``.
+* If you need a new Python package dependency for testing, add it in ``Regression/requirements.txt``
+* Add an entry to ``Regression/WarpX-tests.ini``, so that a WarpX simulation runs your test in the continuous integration process, and the Python script is executed to assess the correctness. For the PML test, the entry is
 
 .. code-block::
 
diff --git a/Docs/source/install/dependencies.rst b/Docs/source/install/dependencies.rst
@@ -25,6 +25,13 @@ Optional dependencies include:
   - see `optional I/O backends <https://github.com/openPMD/openPMD-api#dependencies>`__
 - `CCache <https://ccache.dev>`__: to speed up rebuilds (For CUDA support, needs version 3.7.9+ and 4.2+ is recommended)
 - `Ninja <https://ninja-build.org>`__: for faster parallel compiles
+- `Python 3.6+ <https://www.python.org>`__
+
+  - `mpi4py <https://mpi4py.readthedocs.io>`__
+  - `numpy <https://numpy.org>`__
+  - `periodictable <https://periodictable.readthedocs.io>`__
+  - `picmistandard <https://picmi-standard.github.io>`__
+  - see our ``requirements.txt`` file for compatible versions
 
 
 Install
@@ -67,7 +74,7 @@ If you also want to run runtime tests and added Python (``spack add python`` and
 
 .. code-block:: bash
 
-   python -m pip install matplotlib==3.2.2 yt scipy numpy openpmd-api
+   python3 -m pip install matplotlib==3.2.2 yt scipy numpy openpmd-api virtualenv
 
 If you want to run the ``./run_test.sh`` :ref:`test script <developers-testing>`, which uses our legacy GNUmake build system, you need to set the following environment hints after ``spack env activate warpx-dev`` for dependent software:
 
@@ -118,7 +125,7 @@ Without MPI:
 
 .. code-block:: bash
 
-   conda create -n warpx-dev -c conda-forge blaspp ccache cmake compilers git lapackpp openpmd-api python numpy scipy yt fftw matplotlib mamba ninja
+   conda create -n warpx-dev -c conda-forge blaspp ccache cmake compilers git lapackpp openpmd-api python numpy scipy yt fftw matplotlib mamba ninja pip virtualenv
    source activate warpx-dev
 
    # compile WarpX with -DWarpX_MPI=OFF
@@ -127,7 +134,7 @@ With MPI (only Linux/macOS):
 
 .. code-block:: bash
 
-   conda create -n warpx-dev -c conda-forge blaspp ccache cmake compilers git lapackpp "openpmd-api=*=mpi_openmpi*" python numpy scipy yt "fftw=*=mpi_openmpi*" matplotlib mamba ninja openmpi
+   conda create -n warpx-dev -c conda-forge blaspp ccache cmake compilers git lapackpp "openpmd-api=*=mpi_openmpi*" python numpy scipy yt "fftw=*=mpi_openmpi*" matplotlib mamba ninja openmpi pip virtualenv
    source activate warpx-dev
 
 For legacy ``GNUmake`` builds, after each ``source activate warpx-dev``, you also need to set:
@@ -145,7 +152,7 @@ Apt (Debian/Ubuntu)
 .. code-block:: bash
 
    sudo apt update
-   sudo apt install build-essential ccache cmake g++ git libfftw3-mpi-dev libfftw3-dev libhdf5-openmpi-dev libopenmpi-dev pkg-config python3 python3-matplotlib python3-numpy python3-scipy
+   sudo apt install build-essential ccache cmake g++ git libfftw3-mpi-dev libfftw3-dev libhdf5-openmpi-dev libopenmpi-dev pkg-config python3 python3-matplotlib python3-numpy python3-pip python3-scipy python3-venv
 
    # optional:
    # for CUDA, either install
