fix links, fix code blocks and some rewriting

Author: thorade

README.rst

@@ -2,65 +2,62 @@
 OMPython
 ########
 
-OMPython is a Python interface that uses CORBA (omniORB) or ZeroMQ to communicate with OpenModelica.
+OMPython is a Python interface that uses ZeroMQ or CORBA (omniORB) to communicate with OpenModelica.
 
 Dependencies
 ============
 
-Using omniORB (Python 2 only)
------------------------------
+Using ZeroMQ
+------------
+- Python 2.7 and 3.x supported
+- PyZMQ is required
 
-- Python 2.7 is required (omniORB restriction). Download Python from http://www.python.org/download/
-- omniORB is required
-  - Windows: included in the installer of OpenModelica
-  - Linux: Install omniORB including Python 2 support (the omniidl command needs to be on the PATH)  
-      On Ubuntu, this is done by running `sudo apt-get install omniorb python-omniorb omniidl omniidl-python`
-- Installation using `pip` is recommended.
+Using omniORB
+-------------
+- Currently, only Python 2.7 is supported
+- omniORB is required:
+  - Windows: included in the OpenModelica installation
+  - Linux: Install omniORB including Python 2 support (the omniidl command needs to be on the PATH).
+    On Ubuntu, this is done by running ``sudo apt-get install omniorb python-omniorb omniidl omniidl-python``
 
-Using ZeroMQ (Python 2 and 3 supported)
----------------------------------------
-
-- Python 2.7 or 3.x.x is required. Download Python from http://www.python.org/download/
-- PyZMQ is required.
-- Installation using `pip` is recommended.
 
 Installation
 ============
+Installation using ``pip`` is recommended.
 
 Linux
 -----
+Install the latest OMPython master by running::
 
-```bash
-$ python -m pip install https://github.com/OpenModelica/OMPython/archive/master.zip
-```
+  python -m pip install -U https://github.com/OpenModelica/OMPython/archive/master.zip
 
 Windows
 -------
+Install the version as packaged with your OpenModelica installation by running::
 
-- Add python to your PATH.
-- Start command prompt/terminal and execute commands,
-```powershell
-> cd %OPENMODELICAHOME%\share\omc\scripts\PythonInterface
-> python -m pip install .
-```
-- This will add OMPython to the Python 3rd party libraries.
+  cd %OPENMODELICAHOME%\share\omc\scripts\PythonInterface
+  python -m pip install .
 
 Usage
 =====
+Running the following commads should get you started
+
+.. code-block:: python
+
+  import OMPython
+  help(OMPython)
 
-```python
-import OMPython
-help(OMPython)
-```
+or read the `OMPython documentation <https://openmodelica.org/doc/OpenModelicaUsersGuide/latest/ompython.html>`_ online.
 
 Bug Reports
 ===========
 
-- See OMPython bugs on the [OpenModelica trac](https://trac.openmodelica.org/OpenModelica/query?component=OMPython) or submit a [new ticket](https://trac.openmodelica.org/OpenModelica/newticket).
-- [Pull requests](../../pulls) are welcome.
+- See OMPython bugs on the `OpenModelica trac <https://trac.openmodelica.org/OpenModelica/query?component=OMPython>`_
+  or submit a `new ticket <https://trac.openmodelica.org/OpenModelica/newticket>`_.
+- `Pull requests <https://github.com/OpenModelica/OMPython/pulls>`_ are welcome.
 
 Contact
 =======
 
-Adeel Asghar, adeel.asghar@liu.se<br />
-Arunkumar Palanisamy, arunkumar.palanisamy@liu.se
+- Adeel Asghar, adeel.asghar@liu.se
+- Arunkumar Palanisamy, arunkumar.palanisamy@liu.se