Add pip to install docs (#1127)

* Update the SWIG developer guide on Python

* Add HELICS Python interface install instructions using pip

docs/developer-guide/swig.md

@@ -5,20 +5,22 @@ Generating SWIG extension
 **Python**
 
 The easiest way to generate the latest C files for the Python extension is to use CMake itself.
-For example, you can run the following on an OSX machine where you have `swig` installed.
+For example, you can run the following in a POSIX/Unix environment where you have `swig` installed with Python 3.6.
 
 ```bash
 git clone https://github.com/GMLC-TDC/HELICS
 cd HELICS
-mkdir build-osx
-cmake -DBUILD_PYTHON_INTERFACE=ON -DPYTHON_INCLUDE_DIR=$(python3-config --prefix)/include/python3.6m/ -DCMAKE_INSTALL_PREFIX=/Users/$(whoami)/local/helics-develop/ .. && make -j 8 && make install
+mkdir build
+cmake -DBUILD_PYTHON_INTERFACE=ON -DPYTHON_INCLUDE_DIR=$(python3-config --prefix)/include/python3.6m/ -DCMAKE_INSTALL_PREFIX=$HOME/local/helics-develop/ .. && make -j 8 && make install
 cd swig/python
 cp helicsPYTHON_wrap.c ../../../swig/python/helics_wrap.c
 cp helics.py ../../../swig/python/helics.py
 ```
 
 This method verifies that the C file generated from CMake using SWIG compiles correctly into a Python extension.
 
+For building a Python 2 compatible interface, use BUILD_PYTHON2_INTERFACE instead of BUILD_PYTHON_INTERFACE.
+
 **MATLAB**
 
 For the MATLAB extension, you need a special version of SWIG. Get it [here](https://github.com/jaeandersson/swig).
@@ -33,7 +35,7 @@ The matlab interface can  be built using BUILD_MATLAB_INTERFACE in the cmake bui
 **Octave**
 
 [Octave](https://www.gnu.org/software/octave/) is a free program that works similarly to MATLAB
-Building the octave interface requires swig, and currently will work with Octave 4.0 through 4.2.  4.4 is not currently supported by SWIG unless you build from the current master of the swig repo and use that version.  The next release of swig will likely support it.  It does work on windows, though the actual generation is not fully operational for unknown reasons and will be investigated at some point.  A mkhelicsOCTFile.m is generated in the build directory this needs to be executed in octave, then a helics.oct file should be generated, the libHelicsShared.dll needs to be copied along with the libzmq.dll files Once this is done the library can be loaded by calling helics.   On linux this build step is done for you. with the BUILD_OCTAVE_INTERFACE.
+Building the octave interface requires swig, and currently will work with Octave 4.0 through 4.2.  4.4 is not currently supported by SWIG unless you build from the current master of the swig repo and use that version.  The next release of swig will likely support it.  It does work on windows, though the actual generation is not fully operational for unknown reasons and will be investigated at some point.  A mkhelicsOCTFile.m is generated in the build directory this needs to be executed in octave, then a helics.oct file should be generated, the libHelicsShared.dll needs to be copied along with the libzmq.dll files Once this is done the library can be loaded by calling helics.   On linux this build step is done for you with BUILD_OCTAVE_INTERFACE.
 
 **C#**
 A C# interface can be generated using swig and enabling BUILD_CSHARP_INTERFACE in the CMake. The support is partial; it builds and can be run but not all the functions are completely usable and it hasn't been fully tested.

docs/installation/index.md

@@ -14,12 +14,21 @@ Get the latest installers from [GitHub Releases](https://github.com/GMLC-TDC/HEL
 
 OR
 
-Use conda to install helics:
+Use conda to install the HELICS Python interface and apps:
 
 ```bash
 conda install -c gmlc-tdc helics
 ```
 
+OR
+
+Use pip to install the HELICS Python interface and apps:
+
+```bash
+pip install helics
+pip install helics-apps
+```
+
 ### Using an installer for your operating system
 
 Download pre-compiled libraries from the [releases page](https://github.com/GMLC-TDC/HELICS/releases/latest) and add them to your path.

docs/installation/package_manager.md

@@ -12,3 +12,18 @@ You can then use `conda` to install HELICS.
 conda install -c gmlc-tdc helics
 ```
 
+## Install using pip (Windows, macOS, Linux, other)
+
+Install Python with pip. Upgrade pip to a recent version using `python -m pip install --upgrade`.
+
+If you're on a supported version of Windows, macOS, or Linux (see the [HELICS PyPI page](https://pypi.org/project/helics/) for details) you can then use `pip` to install the HELICS Python interface and helics-apps.
+
+```bash
+pip install helics
+pip install helics-apps
+```
+
+If you are on an unsupported OS or Python version, you will need to install a copy of HELICS first.
+Depending on your OS, there could be a copy in the package manager, or you may need to build HELICS from source.
+From there, you can use `pip install helics` as above (NOTE: `pip install helics-apps` *will not work*, your package manager or HELICS build from source should install these).
+The [source distributions section of the PyPI page](https://pypi.org/project/helics/) has some additional useful information on this process.

docs/introduction/python.md

@@ -8,12 +8,10 @@ We will create a simple `pi-exchange` federation in Python with 2 federates.
 
 Before we run the Python `pi-exchange` federation, it is necessary to ensure that we have Python installed and that we have the HELICS Python built successfully and correctly on the machine.
 
-We recommend using Anaconda3/Miniconda3, although this should work with most versions of Python.
-To make an interface that is similar across different languages, we use SWIG to generate the Python bindings to the `helicsSharedLib` shared library.
+We recommend using pip with Python (version 2.7 or 3.5+) or Anaconda3/Miniconda3 to install a copy of the HELICS Python interface, although this should work with most versions of Python if you build the interface yourself using SWIG to generate the Python bindings to the `helicsSharedLib` shared library.
 SWIG claims to be compatible with most Python versions, dating back to Python 2.0. And recommends that for the best results, one should consider using Python 2.3 or newer.
 
-HELICS can also be built from source and linked with the required Python version.
-See the page on the Installation instructions for more information regarding this.
+See the Installation instructions page for more information regarding this.
 
 **Create a federations directory**