New documentation for getting started

docs/start/index.rst

@@ -10,71 +10,92 @@ Getting Started
 Requirements
 ------------
 
-For scientist we require to install Anaconda, because it makes
-easy to get all dependencies. 
-Download and install `here <https://www.anaconda.com/download>`_.
-Make sure to download the latest version with python 3.6.
+You need a working python 3.x installation to be able to use QCoDeS. We highly
+recommend installing Anaconda, which takes care of installing Python and
+managing packages. In the following it will be assumed that you use Anaconda.
+Download and install it from `here <https://www.anaconda.com/download>`_. Make
+sure to download the latest version with python 3.6.
 
-Once you download, install Anaconda according to the instructions on screen.
-
-If you use \*nix, you really should use the source.
+Once you download, install Anaconda according to the instructions on screen,
+choosing the single user installation option.
 
 The next section will guide you through the installation of QCoDeS
-on Windows, although most of the things also work for osx and Linux.
-(that is, assuming you did not change your $PATH, and or have virtual envs,
-but in that case you should once more just use the source)
+on Windows, although most of the things also work for macOS and Linux.
 
 Installation
 ------------
+Before you install QCoDeS you have to decide whether you want to install the
+latest stable release or if you want to get the developer version from GitHub.
 
-To setup an Anaconda environment for QCoDeS it's convenient to download
-QCoDeS environment.yml file from
-`here <https://github.com/QCoDeS/Qcodes/blob/master/environment.yml>`__.
-Right click on `this link <https://raw.githubusercontent.com/QCoDeS/Qcodes/master/environment.yml>`__
+Installing the latest QCoDeS release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+First download the QCoDeS environment.yml file by right
+clicking on `this link <https://raw.githubusercontent.com/QCoDeS/Qcodes/master/environment.yml>`__
 and select save link as and download the file to a location
 that you can find again.
-Once Anaconda is installed and the environment.yml file downloaded
-launch an Anaconda Prompt.
+Next launch an Anaconda Prompt (start typing anaconda in the start menu and
+click on *Anaconda Prompt*).
 
-Now you are ready to install QCoDeS, type in the terminal.
+Here type in the prompt:
 
 .. code:: bash
 
     conda env create -f environment.yml
+    activate qcodes
     pip install qcodes
 
-Enter QCoDes
-------------
-In  general follow this steps to get a terminal back:
+The first line creates a new anaconda environment that is called *qcodes*
+and will install all the required dependendencies. The second line activates
+this freshly created environment, so that the command in the third line will
+install qcodes for this environment.
 
+Installing QCoDeS from GitHub
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Clone the QCoDeS repository from GitHub from https://github.com/QCoDeS/Qcodes
+Then create an environment, that contains all of the dependencies for QCoDeS,
+from the *environment.yml* file in the root of the repository and activate it:
 
-- Open navigator
-- On the left side click on "Environments".
-- Click qcodes to activate it
-- Click the green arrow to open a terminal inside it.
+.. code:: bash
 
-Now go to the directory of your experiment, and start a notebook or spyder.
+    conda env create -f <path-to-environment.yml>
+    activate qcodes
+
+Finally install QCoDeS add the repository via
 
 .. code:: bash
 
-    cd my_experiment
-    jupyter notebook
+    pip install -e <path-to-repository>
+
 
-or
+Using QCoDes
+------------
+For using QCoDeS, as with any other python library, it is useful to use an
+application that facilitates the editing and execution of python files. With
+Anaconda there come two preinstalled options:
+
+ * **Jupyter**, a browser based notebook
+ * **Spyder**, an integrated development environment
+
+To start either of them you can use the shortcuts in the start menu under
+*Anaconda3* with a trailing *(qcodes)*.
+
+For other options you can launch a terminal either via the *Anaconda Navigator*
+by selecting *qcodes* in the *Environments tab* and left-clicking on the *play*
+button or by entering
 
 .. code:: bash
 
-    cd my_experiment
-    spyder
+    activate qcodes
+
+in the *Anaconda prompt*
 
-Then:
+From the terminal you can then start any other application, such as *IPython* or
+just plain old *Python*.
 
-  - build quantum computer
-  - profit
 
-Usage
------
+Getting started
+---------------
 
-Read the :ref:`userguide`, and or browse the examples:
+Have a look at :ref:`userguide`, and or browse the examples at:
 
    https://github.com/QCoDeS/Qcodes/tree/master/docs/examples