documentation about installation and python getting started (#582)

* updated installation documention, added Python find virtual env flag

docs/src/installation.rst

@@ -13,54 +13,143 @@
     
     Before building from source make sure that you have the 
     :doc:`dependencies <../dependencies>` installed. If installing using conda, conda will 
-    manage the dependencies.
+    manage the dependencies. Avoid also installing packages with pip. 
    
 
 .. _Installation:
 
+
 Installation
-==============================================
+===============
 
-.. _build from source using cmake:
+Install binaries using conda
+-------------------------------
 
-Build from source using CMake
+Conda is not only useful to manage python environments but can also
----------------------------------
+be used as a user space package manager. Dates in the tag (for eg. 2020.07.23.dev0) 
+are from the developer branch. Please use released tags for stability.
 
-Note that on some systems, for example RH7,  cmake v3+ is available under the cmake3 alias.
+We have three different packages available:
-It is also required to clone with the option --recursive to get the pybind11 submodules used
+
-in the package. (Only needed for older versions than v7.0.0)
+    * **slsdetlib** shared libraries and command line utilities 
+    * **slsdetgui** GUI
+    * **slsdet** Python bindings
+
+.. code-block:: bash
+
+    #Add channels for dependencies and our library
+    conda config --add channels conda-forge
+    conda config --add channels slsdetectorgroup
+    conda config --set channel_priority strict
+
+    #create and activate an environment with our library
+    #replace 6.1.1 with the required tag
+    conda create -n myenv slsdetlib=6.1.1
+    conda activate myenv
+
+    #ready to use
+    sls_detector_get exptime
+    etc ...
 
 
 .. code-block:: bash
 
+    #List available versions
+    conda search slsdet
+
+
+
+Build from source
+-------------------
+
+
+1. Download Source Code from github
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+    git clone https://github.com/slsdetectorgroup/slsDetectorPackage.git --branch 6.1.1
+
+
+| **Pybind**
+| v7.0.0+:
+|   pybind11 packaged into 'libs/pybind'. No longer a submodule. No need for "recursive" or "submodule update".
+| 
+| Older versions:
+|   pybind11 is a submodule> Must be cloned using "recursive" and updated when switching between versions using the following commands.
+
+.. code-block:: bash
+    
+    # clone using recursive to get pybind11 submodule
     git clone --recursive https://github.com/slsdetectorgroup/slsDetectorPackage.git
 
-    # if older than v7.0.0 and using python, update pybind11 submodules
+    # update submodule when switching between releases
     cd slsDetectorPackage
     git submodule update --init
    
-    mkdir build && cd build
-    cmake ../slsDetectorPackage -DCMAKE_INSTALL_PREFIX=/your/install/path
-    make -j12 #or whatever number of cores you are using to build
-    make install
 
-The easiest way to configure options is to use the ccmake utility. 
+.. _build from source using cmake:
+
+
+
+2. Build from Source
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Build using CMake
+^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: bash
 
-    #from the build directory
+    # outside slsDetecorPackage folder
-    ccmake .
+    mkdir build && cd build
+
+    # configure & generate Makefiles using cmake
+    # by listing all your options (alternately use ccmake described below)
+    # cmake3 for some systems
+    cmake ../slsDetectorPackage -DCMAKE_INSTALL_PREFIX=/your/install/path
+
+    # compiled to the build/bin directory
+    make -j12 #or whatever number of cores you are using to build
+
+    # install headers and libs in /your/install/path directory
+    make install
 
 
-Build using cmk.sh script
+Instead of the cmake command, one can use ccmake to get a list of options to configure and generate Makefiles at ease.
--------------------------
+
-These are mainly aimed at those not familiar with using ccmake and cmake.
+.. code-block:: bash
+
+    # ccmake3 for some systems
+    ccmake ..
+ 
+    # choose the options
+    # first press [c] - configure
+    # then press [g] - generate
+
+
+
+===============================     ===========================================
+Example cmake options               Comment
+===============================     ===========================================
+-DSLS_USE_PYTHON=ON                 Python
+-DPython_FIND_VIRTUALENV=ONLY       Python from only the conda environment 
+-DZeroMQ_HINT=/usr/lib64            System zmq instead of conda
+-DSLS_USE_GUI=ON                    GUI
+===============================     ===========================================
+
+
+
+Build using in-build cmk.sh script
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 
 .. code-block:: bash
 
     The binaries are generated in slsDetectorPackage/build/bin directory.
 
-    Usage: ./cmk.sh [-b] [-c] [-d <HDF5 directory>] [e] [g] [-h] [i] [-j <Number of threads>] [-k <CMake command>] [-l <Install directory>] [m] [n] [-p] [-q <Zmq hint directory>] [r] [s] [t] [u] [z]  
+    Usage: ./cmk.sh [-b] [-c] [-d <HDF5 directory>] [e] [g] [-h] [i] [-j <Number of threads>] 
+    [-k <CMake command>] [-l <Install directory>] [m] [n] [-p] [-q <Zmq hint directory>] 
+    [r] [s] [t] [u] [z]  
     -[no option]: only make
     -b: Builds/Rebuilds CMake files normal mode
     -c: Clean
@@ -86,48 +175,18 @@ These are mainly aimed at those not familiar with using ccmake and cmake.
     # get all options
     ./cmk.sh -?
 
-    # new build  and compile in parallel:
+    # new build and compile in parallel:
     ./cmk.sh -bj5
 
+    # new build, python and compile in parallel:
+    ./cmk.sh -bpj5
 
-Install binaries using conda
+    #To use the system zmq (/usr/lib64) instead of conda
---------------------------------
+    ./cmk.sh -bj5 -q /usr/lib64
-
-Conda is not only useful to manage python environments but can also
-be used as a user space package manager. 
-
-We have three different packages available:
-
- * **slsdetlib**, shared libraries and command line utilities 
- * **slsdetgui**, GUI
- * **slsdet**, Python bindings
 
 
-.. code-block:: bash
+Build on old distributions
-
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    #Add channels for dependencies and our library
-    conda config --add channels conda-forge
-    conda config --add channels slsdetectorgroup
-    conda config --set channel_priority strict
-
-    #cerate an environment with our library, then activate
-    #replace 2020.07.20.dev0 with the required tag
-    conda create -n myenv slsdetlib=2020.07.23.dev0
-    conda activate myenv
-
-    #ready to use
-    sls_detector_get exptime
-    etc ...
-
-
-.. code-block:: bash
-
-    #List available versions
-    conda search slsdet
-
-
-Build from source on old distributions
------------------------------------------
 
 If your linux distribution doesn't come with a C++11 compiler (gcc>4.8) then 
 it's possible to install a newer gcc using conda and build the slsDetectorPackage
@@ -138,6 +197,9 @@ using this compiler
     #Create an environment with the dependencies
     conda create -n myenv gxx_linux-64 cmake zmq
     conda activate myenv
+
+    # outside slsDetecorPackage folder
+    mkdir build && cd build
     cmake ../slsDetectorPackage -DCMAKE_PREFIX_PATH=$CONDA_PREFIX
     make -j12
 

docs/src/pygettingstarted.rst

@@ -14,25 +14,10 @@ also for non Python packages but there are also other alternatives like, pyenv.
 Using something like conda also allows you to quickly switch beteen different Python 
 environments. 
 
-.. warning ::
+.. note ::
 
-    If you use conda avoid also installing packages with pip. 
+    Ensure that the python lib compiled is for the expected python version.
----------------------
+    For example, build/bin/_slsdet.cpython-39-x86_64-linux-gnu.so for Python v3.9.x
-PYBIND11 
----------------------
-**v7.0.0 of slsDetectorPackage:**
-
-#. It is packaged into libs (pybind)
-#. No longer a submodule of the slsDetectorPackage
-
-**Older than v7.0.0:**
-
-#. Submodule in libs (pybind11)
-#. Switching between versions will require an update of the submodule as well using:
-
-.. code-block:: bash
-
-    git submodule update --init  #from the main slsDetectorPackage folder
 
 ---------------------
 PYTHONPATH 

docs/src/slsreceiver.rst

@@ -160,7 +160,7 @@ When handling callbacks, the control should be returned as soon as possible, to
 **Example**
     * `main cpp file <https://github.com/slsdetectorgroup/api-examples/blob/master/e4-receiver_callbacks.cpp>`_ 
     * `cmake file <https://github.com/slsdetectorgroup/api-examples/blob/master/CMakeLists.txt>`_. 
-    * how to install the slsDetectorPackage is provided :ref:`here <build from source using cmake>`.
+    * how to install the slsDetectorPackage with cmake is provided :ref:`here <build from source using cmake>`.
     * compile the example **e4-rxr** by:
 
         .. code-block:: bash