Added introduction and basics of installation

doc/index.rst

@@ -6,7 +6,13 @@
 Welcome to the Modelverse documentation!
 ========================================
 
-Contents:
+This document contains all practical information regarding the Modelverse.
+References to the papers describing the theoretical concepts are made throughout the documentation.
+As such, this document is a practical introduction to (meta-)modelling in the Modelverse.
+
+We make the distinction between three types of users of the Modelverse: modellers, language engineers, and developers.
+Depending on your goals of using the Modelverse, you will fall into one of these categories.
+Due to the design of the Modelverse, where everything is a model, the hierarchy is cumulative: language require knowledge of modelling, and developers require knowledge of language engineer and modelling.
 
 .. toctree::
    :maxdepth: 2

doc/installation.rst

@@ -1,14 +1,33 @@
 Installation
 ============
 
+Installation of the Modelverse is rather simple, as is its simple usage.
+We first introduce the dependencies of the Modelverse, followed by installation instructions for the Modelverse itself.
+To check whether or not the installation was successful, users can run the enclosed tests.
+
 Dependencies
 ------------
 
 The Modelverse reference implementation is relatively dependency-free.
 As its code is written in Python 2, a working Python 2.7 interpreter is necessary.
-
-To run the tests, this interpreter needs to have the `pytest <http://docs.pytest.org/en/latest/>`_ module installed.
 To run the server, the `SCCD <https://msdl.uantwerpen.be/git/simon/SCCD>`_ module needs to be installed.
+Full installation instructions can be found on the project website.
+
+To run the tests, the `pytest <http://docs.pytest.org/en/latest/>`_ module must be installed.
+In case you want to use PyPy, which often offers increased performance, you need to install both dependencies in PyPy as well.
+Next, we document how this is done.
+
+PyPy
+^^^^
+
+For SCCD, you can simply install it using PyPy instead of CPython.
+
+For pytest, you also need to install all of pytest's dependencies, and pytest itself.
+The easiest way to do this is through *pip*, which you also have to install first for PyPy::
+
+    wget https://msdl.uantwerpen.be/files/get-pip.py
+    pypy get-pip.py --user
+    pypy -m pip install pytest --user
 
 Installation
 ------------
@@ -16,18 +35,18 @@ Installation
 The Modelverse is merely a set of Python scripts, and there is no real installation, except for its dependencies.
 As such, you will only have to download the source code and are ready to use the Modelverse.
 
-0. Install dependencies.
-1. Download the `Modelverse source code <https://msdl.uantwerpen.be/git/yentl/modelverse>`_.
-   For example using git::
+To install the Modelverse, download the `Modelverse source code <https://msdl.uantwerpen.be/git/yentl/modelverse>`_.
+This can be done through git::
 
     git clone https://msdl.uantwerpen.be/git/yentl/modelverse
 
-   Or using your favorite HTTP download tool::
+Or using your favorite HTTP download tool::
 
     wget https://msdl.uantwerpen.be/git/yentl/modelverse/archive/master.zip
     unzip master.zip
 
-2. That's it! You can now run the scripts in the *scripts/* directory using Python.
+You can now run the scripts in the *scripts/* directory using Python.
+In the next section, we go deeper into the relevant scripts.
 
 Tests
 -----
@@ -38,37 +57,13 @@ Executing the tests is as simple as the following command::
 
     python scripts/run_tests.py
 
-This will run a set of tests for all different projects.
-Note that this also causes some bootstrap files to be created, which might take some time on slow machines.
-A faster alternative is to only run the overall tests::
-
-    python -m pytest integration
-
-PyPy
-^^^^
-
-The default way of executing tests is probably through CPython.
-Note, however, that CPython is a slow implementation of Python, which makes everything in the Modelverse slower.
-While it is not impossible to use CPython, using PyPy is recommended for the server!
-Nonetheless, PyPy is often not the default interpreter.
-You will therefore have to explicitly give control to PyPy instead of CPython.
-
-This is fairly simple: all scripts in *scripts/* execute their subprocesses using the Python interpreter used to start the script.
-As such, the following command suffices to execute the Modelverse tests using PyPy::
-
-    pypy scripts/run_tests.py
+.. note::
 
-The problem, however, is that all modules need to be readily installed on PyPy.
-For SCCD, you can simply install it using PyPy instead of CPython.
-For pytest, you also need to install all of pytest's dependencies.
-The easiest way to do this is through *pip*, which you also have to install first::
+   If you prefer to use PyPy, you can similarly execute it by replacing *python* with *pypy*.
+   All occurences of *python* can be replaced by *pypy*, as long as both implement Python 2.7.
 
-    wget https://msdl.uantwerpen.be/files/get-pip.py
-    pypy get-pip.py --user
-    pypy -m pip install pytest --user
-
-Afterwards, you can simply run::
-
-    pypy scripts/run_tests.py
+This will run a set of tests for all different projects.
+Note that this also causes some bootstrap files to be created, which might take some time on slow machines, certainly if PyPy is not used.
+A faster alternative is to run the faster tests, though this will not test the creation of bootstrap files::
 
-To execute the tests using PyPy.
+    python scripts/run_fast_tests.py