diff --git a/README.rst b/README.rst
index f781a0607d967313139e64fd7d2c827bf3beba1a..4fba76a33d61c89a9471785c354905ff2fd0e47d 100644
--- a/README.rst
+++ b/README.rst
@@ -1,7 +1,66 @@
+Offline Calibration
+===================
+
+The offline calibration is a package that consists of different services,
+responsible for applying most of the offline calibration and characterization
+for the detectors.
+
+Offline calibration installation
+================================
+
+It's recommended to install the offline calibration (pycalibration) package
+over maxwell, using anaconda/3 environment.
+
+Installation using Anaconda
+---------------------------
+
+First you need to load the anaconda/3 environment through::
+
+    1. module load anaconda/3
+
+If installing into other python enviroments, this step can be skipped.
+
+Then the package for the offline calibration can be obtained from the git repository::
+
+    2. git clone https://git.xfel.eu/gitlab/detectors/pycalibration.git
+
+
+You can then install all requirements of this tool chain in your home directory by running::
+
+    3. pip install -r requirements.txt . --user
+
+in pycalibration's root directory.
+
+After installation, you should make sure that the home directory is in the PATH environment variable::
+
+    4. export PATH=$HOME/.local/bin:$PATH
+
+
+Development Installation
+------------------------
+
+For a development installation in your home directory, which automatically
+picks up (most) changes, first install the dependencies as above,
+but then install the tool-chain separately in development mode::
+
+   pip install -e . --user
+
+
+Activate Offline calibration
+============================
+
+For using pycalibration package one needs to activate it through::
+
+    source activate
+
+from inside of the pycalibration directory. This will automatically load 
+all needed modules and export the $PATH for the home directory.
+
+
 Python Scripted Calibration
 ===========================
 
-First: do not run this on the Maxell gateway. Rather, `salloc`
+First: do not run this on the Maxwell gateway. Rather, `salloc`
 a node for yourself first::
 
    salloc -p exfel/upex -t 01:00:00
@@ -47,10 +106,3 @@ to provid accurate relative gain correction constants.
 
 You'll get a series of plots in the output directory as well.
 
-
-
-
-
-
-
-
diff --git a/requirements.txt b/requirements.txt
index 90228cd8cb16bfa7ec5dea7acb83835504e3ae4a..a42e0aedaa44503087dd629040a9a2a8b4b53a8e 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -17,6 +17,7 @@ sklearn
 prettytable
 jupyter
 jupyter_console
-sphinx == 1.4.5
+metadata_client
+sphinx == 1.8.5
 ./cal_tools
 .