wrapping up installation doc

Geodels · Jun 21, 2024 · 7320398 · 7320398
1 parent 1840e26
commit 7320398
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 35 deletions.
diff --git a/docs/getting_started/installConda.rst b/docs/getting_started/installConda.rst
@@ -1,6 +1,6 @@
 .. _installConda:
 
-Installing goSPL and its dependencies stack from source can be a **tedious and difficult**.
+Installing goSPL and its dependencies stack from source can be **tedious and difficult**.
 
 
 =========================
@@ -12,7 +12,7 @@ Installation via Conda
 
 .. important::
 
-    This is the recommended approach to install and use goSPL.
+    This is the preferred approach to install and use goSPL.
 
 
 .. warning::
@@ -114,3 +114,18 @@ To verify that the environment was removed, in your terminal window or an Anacon
 
 
 The ``gospl`` conda environment should not be in your list of environment anymore.
+
+
+Alternative goSPL installation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You might want to try another branch/version of goSPL. To do so you could once your conda environment has been activated run the following::
+
+    pip install git+https://github.com/Geodels/gospl.git@NAME
+
+
+where ``NAME`` needs to be replaced by the branch/version you want to try.
+
+Alternatively, you could clone or download the goSPL `repository <https://github.com/Geodels/gospl/archive/refs/heads/master.zip>`_ and run the following command in the repository directory::
+
+    pip install --no-build-isolation -e .
diff --git a/docs/getting_started/installPypi.rst b/docs/getting_started/installPypi.rst
@@ -1,31 +1,28 @@
 .. _installPypi:
 
 
-The following installation guidelines are mainly for experienced users working on a Linux environment. It is highly recommended to use ``docker`` or ``conda``, for quick installation and for package and dependency updates.
-You can find simple installation instructions for :mod:`gospl` in this document.
+The following installation guidelines are mainly for **experienced** users working on a Linux environment. It is highly recommended to use ``conda`` for quick installation and for packages and dependencies updates. 
 
 =========================
 Installation via PyPI
 =========================
 
-:mod:`gospl` can be installed via pip from
-`PyPI <https://pypi.org/project/gospl>`__.
+.. warning::
 
-::
+    The `PyPI <https://pypi.org/project/gospl>`__ goSPL installation is limited and might not be fully functional in many cases
+
+You might want to give it a try by running the following command::
 
     pip install gospl
 
-The installation however requires additional dependencies and is likely to
-failed if some initial packages are not already available. When using ``pip``,
-it is recommended to use ``virtualenv``. For a guide on how to use it, readers
-are invited to look at visit the `Python documentation <https://docs.python.org/3/tutorial/venv.html>`_.
+The installation however requires additional dependencies and is likely to failed if some initial packages are not already available. When using ``pip``, it is recommended to use ``virtualenv``. For a guide on how to use it, readers are invited to look at visit the `Python documentation <https://docs.python.org/3/tutorial/venv.html>`_.
 
 
 Installing dependencies
 -----------------------------
 
 
-On linux, you will need to install ``MPI``, ``PETSc`` and ``Hdf5`` via the your Linux distribution's package manager.
+On linux, you will need to install ``MPI``, ``PETSc`` and ``Hdf5`` from your Linux distribution's package manager.
 
 
 For example, the commands in this table will install ``MPICH`` from your distribution.
@@ -58,12 +55,23 @@ If you have ``PETSc`` already installed, you can point to your ``PETSC_DIR`` and
     unset PETSC_ARCH
 
 
-Installing ``PETSc`` and ``gospl``
+Installing PETSc and dependencies
 -----------------------------------
 
-Then the remaining library are installed locally by running::
+Then the remaining libraries are installed locally by running::
 
+    sudo apt-get install proj-bin
     pip install --upgrade pip setuptools wheel
     pip install petsc --user
     pip install petsc4py --user
-    pip install gospl --user
+    pip install xarray --user
+    pip install pyproj --user
+    
+
+And finally to install goSPL::
+
+    pip install git+https://github.com/Geodels/gospl.git
+
+Alternatively, you could clone or download the goSPL `repository <https://github.com/Geodels/gospl/archive/refs/heads/master.zip>`_ and run the following command in the repository directory::
+
+    pip install --no-build-isolation -e .
diff --git a/docs/getting_started/installSrc.rst b/docs/getting_started/installSrc.rst
@@ -6,18 +6,20 @@ Installation via Source
 
 .. note::
 
-  Below are some of the main instructions to build :mod:`gospl` from the git source tree. This approach is mainly for experienced users working on a Linux environment. It is highly recommended to use ``docker`` or ``conda``, for quick installation and for package and dependency updates.
+  Below are some of the main instructions to build goSPL from the git source tree. This approach is mainly for **experienced** users working on a Linux environment. It is highly recommended to use ``conda``, for quick installation and for packages and dependencies updates.
 
 
 Update System
 --------------
 
-  apt-get update -qq
-  apt-get install -yq --no-install-recommends bash-completion build-essential
-  apt-get install -yq --no-install-recommends python3-minimal python3-dev python3-pip
-  apt-get install -yq --no-install-recommends python3-tk python3-dbg cmake
-  apt-get install -yq --no-install-recommends python3-setuptools wget gfortran
+::
 
+      apt-get update -qq
+      apt-get install -yq --no-install-recommends bash-completion build-essential
+      apt-get install -yq --no-install-recommends python3-minimal python3-dev python3-pip
+      apt-get install -yq --no-install-recommends python3-tk python3-dbg cmake
+      apt-get install -yq --no-install-recommends python3-setuptools wget gfortran
+      apt-get install -yq --no-install-recommends proj-bin
 
 MPICH
 -------
@@ -77,9 +79,7 @@ PETSc
 Dependencies
 ----------------------
 
-:mod:`gospl` has many required dependencies. If a
-dependency is not installed, :mod:`gospl` will raise an ``ImportError`` when
-the method/class requiring that dependency is called.
+goSPL has many required dependencies. If a dependency is not installed, goSPL will raise an ``ImportError`` when the method/class requiring that dependency is called.
 
 A dependency ``XXXX`` is installed via the following command in a terminal::
 
@@ -102,26 +102,34 @@ meshplex                  0.13.4             Fast tools for simplex meshes
 pre-commit                2.7.1              Managing and maintaining multi-language pre-commit hooks
 vtk                       9.0.3              Toolkit for 3D computer graphics and image processing
 numpy-indexed             0.3.5              Functionality for indexed operations on numpy ndarrays
+xarray                    0.15.0             Labelled multi-dimensional arrays 
+pyproj                    2.5.0              Interface to PROJ (coordinate transformations)
+gflex                     1.1.0              Methods to solve elastic plate flexure
 ========================= ================== =============================================================
 
 
-Setup install
+Meshplex work-around
 ----------------------
 
-Once all the listed dependencies above have been installed, :mod:`gospl`
-source files are available through `GitHub <https://github.com/Geodels/gospl>`_::
 
-      git clone https://github.com/Geodels/gospl
+In case where you are asked to download a licensed version of Meshplex, you might want to try the following alternatives:
 
-It can then be installed locally on your system using::
+1. Use the version available from conda (conda install meshplex) this is version ``v0.15.14`` which is open-source and should work well.
+2. Download an older repository of Meshplex such as the one from `Geodels <https://github.com/Geodels/meshplex>`_ ``v0.8.0`` or from `here <https://github.com/kinnala/meshplex>`_ ``v0.13.3`` or `here <https://github.com/cottrell/meshplex>`_ ``v0.17.0`` 
 
-      python setup.py install --user
+If you use option 2 and once the folder is downloaded, you can install the code by running in a terminal:: 
+
+      python3 -m pip install . 
 
-If you wish to uninstall **gospl** you can do::
 
-      python3 setup.py install --record gospl-files.txt
+goSPL installation
+----------------------
+
+Once all the listed dependencies above have been installed, goSPL source files are available through `GitHub <https://github.com/Geodels/gospl>`_::
+
+      git clone https://github.com/Geodels/gospl
+
+It can then be installed locally on your system using::
 
-To record a list of installed files in ``gospl-files.txt``. Once you want to uninstall you can
-use ``xargs`` to proceed with the uninstall::
+      pip install --no-build-isolation -e .
 
-      xargs rm -rf < gospl-files.txt