Merge branch 'feat/readme-ssh-key-instructions' into 'master'

Add instructions on setting up GitLab SSH to README

See merge request detectors/pycalibration!455

README.rst

@@ -12,8 +12,13 @@ for the detectors.
 Offline Calibration Installation
 ********************************
 
-It's recommended to install the offline calibration (pycalibration) package over
-maxwell, using anaconda/3 environment.
+It's recommended to install the offline calibration (pycalibration) package on
+maxwell, using the anaconda/3 environment.
+
+The following instructions clone from the EuXFEL GitLab instance using SSH
+remote URLs, this assumes that you have set up SSH keys for use with GitLab
+already. If you have not then read the appendix section on `SSH Key Setup for
+GitLab`_ for instructions on how to do this .
 
 
 Installation using python virtual environment - recommended
@@ -251,6 +256,38 @@ Important information that doesn't really fit in as part of the readme.
 TODO: Place this into the docs? Also, improve docs (out of scope for PR !437)
 
 
+SSH Key Setup for GitLab
+========================
+
+It is highly recommended to set up SSH keys for access to GitLab as this
+simplifies the setup process for all of our internal software present on GitLab.
+
+To set up the keys:
+
+1. Connect to Maxwell
+2. Generate a new keypair with ``ssh-keygen -o -a 100 -t ed25519``, you can
+   either leave this in the default location (``~/.ssh/id_ed25519``) or place it
+   into a separate directory to make management of keys easier if you already
+   have multiple ones. If you are using a password for your keys please check
+   this page to learn how to manage them: https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent
+3. Add the public key (``id_ed25519.pub``) to your account on GitLab: https://git.xfel.eu/gitlab/profile/keys
+4. Add the following to your ``~/.ssh/config`` file
+
+.. code::
+
+  # Special flags for gitlab over SSH
+  Host git.xfel.eu
+      User git
+      Port 10022
+      ForwardX11 no
+      IdentityFile ~/.ssh/gitlab/id_ed25519
+
+Once this is done you can clone repositories you have access to from GitLab
+without having to enter your password each time. As ``pycalibration``
+requirements are installed from SSH remote URLs having SSH keys set up is a
+requirement for installing pycalibration.
+
+
 GitLab Access for ``xcaltst`` and ``xcal``
 ==========================================