Rewrite part of the README to make it more user-friendly (#279)

The README file is slightly out of date and not very user-friendly anyway, this is an attempt to fix that.

README.rst

@@ -1,92 +1,126 @@
 Installation
 ============
 
-Dependencies can be installed using setup.py in the same way as synapse: see synapse/README.rst.  For instance::
+Installing the system dependencies
+----------------------------------
 
-    sudo apt-get install build-essential python2.7-dev libffi-dev \
+To install Sydent's dependencies on a Debian-based system, run::
+
+    sudo apt-get install build-essential python3-dev libffi-dev \
                          sqlite3 libssl-dev python-virtualenv libxslt1-dev
 
-    virtualenv -p python2.7 ~/.sydent
+Creating the virtualenv
+-----------------------
+
+To create the virtual environment in which Sydent will run::
+
+    virtualenv -p python3 ~/.sydent
     source ~/.sydent/bin/activate
     pip install --upgrade pip
     pip install --upgrade setuptools
-    pip install https://github.com/matrix-org/sydent/tarball/master
 
-Having installed dependencies, you can run sydent using::
 
-    python -m sydent.sydent
+Installing the latest Sydent release from PyPI
+----------------------------------------------
 
-This will create a configuration file in sydent.conf with some defaults. You'll most likely want to change the server name and specify a mail relay.
+Sydent and its dependencies can be installed using ``pip`` by running::
 
-Defaults for SMS originators will not be added to the generated config file, these should be added in the form::
+    pip install matrix-sydent
 
-    originators.<country code> = <long|short|alpha>:<originator>
+Installing from source
+----------------------
 
-Where country code is the numeric country code, or 'default' to specify the originator used for countries not listed. For example, to use a selection of long codes for the US/Canda, a short code for the UK and an alphanumertic originator for everywhere else::
+Alternatively, Sydent can be installed using ``pip`` from a local git checkout::
 
-    originators.1 = long:12125552368,long:12125552369
-    originators.44 = short:12345
-    originators.default = alpha:Matrix
+    git clone https://github.com/matrix-org/sydent.git
+    cd sydent
+    pip install -e .
 
-Testing
-=======
 
-Sydent uses matrix-is-tester (https://github.com/matrix-org/matrix-is-tester/) to provide black-box testing of its API.
-This can be run as follows:
+Running Sydent
+==============
 
-    pip install git+https://github.com/matrix-org/matrix-is-tester.git
-    trial matrix_is_tester
+With the virtualenv activated, you can run Sydent using::
 
-The SYDENT_PYTHON enviroment variable can be set to launch sydent with a specific python binary:
+    python -m sydent.sydent
 
-    SYDENT_PYTHON=/path/to/python trial matrix_is_tester
+This will create a configuration file in ``sydent.conf`` with some defaults. If a setting is
+defined in both the ``[DEFAULT]`` section and another section in the configuration file,
+then the value in the other section is used.
+
+You'll most likely want to change the server name (``server.name``) and specify an email server
+(look for the settings starting with ``email.``).
+
+By default, Sydent will listen on ``0.0.0.0:8090``. This can be changed by changing the values for
+the configuration settings ``clientapi.http.bind_address`` and ``clientapi.http.port``.
 
-The matrix_is_test directory contains sydent's launcher for matrix_is_tester: this needs to be on the
-python path.
+Sydent uses SQLite as its database backend. By default, it will create the database as ``sydent.db``
+in its working directory. The name can be overridden by modifying the ``db.file`` configuration option.
+Sydent is known to be working with SQLite version 3.16.2 and later.
 
-Requests
-========
+SMS originators
+---------------
 
-The requests that synapse servers and clients submit to the identity server are, briefly, as follows:
+Defaults for SMS originators will not be added to the generated config file, these should
+be added to the ``[sms]`` section of that config file in the form::
 
-Request the validation of your email address::
+    originators.<country code> = <long|short|alpha>:<originator>
+
+Where country code is the numeric country code, or ``default`` to specify the originator
+used for countries not listed. For example, to use a selection of long codes for the
+US/Canada, a short code for the UK and an alphanumertic originator for everywhere else::
 
-    curl -XPOST 'http://localhost:8090/_matrix/identity/api/v1/validate/email/requestToken' -H "Content-Type: application/json" -d '{"email": "matthew@arasphere.net", "client_secret": "abcd", "send_attempt": 1}'
-    {"success": true, "sid": "1"}
+    originators.1 = long:12125552368,long:12125552369
+    originators.44 = short:12345
+    originators.default = alpha:Matrix
 
-(Receive 943258 by mail)
+Testing
+=======
 
-Use this code to validate your email address::
+Sydent uses matrix-is-tester (https://github.com/matrix-org/matrix-is-tester/) to provide
+black-box testing of compliance with the `Matrix Identity Service API <https://matrix.org/docs/spec/identity_service/latest>`_.
+This can be run as follows::
 
-    curl -XPOST 'http://localhost:8090/_matrix/identity/api/v1/validate/email/submitToken' -H "Content-Type: application/json" -d '{"token": "943258", "sid": "1", "client_secret": "abcd"}'
-    {"success": true}
+    pip install git+https://github.com/matrix-org/matrix-is-tester.git
+    trial matrix_is_tester
 
-Use the validated email address to bind it to a matrix ID::
+The ``SYDENT_PYTHON`` enviroment variable can be set to launch Sydent with a specific python binary::
 
-    curl -XPOST 'http://localhost:8090/_matrix/identity/api/v1/3pid/bind' -H "Content-Type: application/json" -d '{"sid": "1", "client_secret": "abcd", "mxid": "%40matthew%3amatrix.org"}'
+    SYDENT_PYTHON=/path/to/python trial matrix_is_tester
 
-Lookup::
+The ``matrix_is_test`` directory contains Sydent's launcher for ``matrix_is_tester``: this means
+that Sydent's directory needs to be on the Python path (e.g. ``PYTHONPATH=$PYTHONPATH:/path/to/sydent``).
 
-    curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=henry%40matrix.org'
+Sydent also has some unit tests to ensure some of its features that aren't part of the Matrix
+specification (e.g. replication) keep on working. To run these tests, run the following with Sydent's
+virtualenv activated from the root of the Sydent repository::
 
-Fetch pubkey key for a server::
+     trial tests
 
-    curl http://localhost:8090/_matrix/identity/api/v1/pubkey/ed25519:0
 
-Internal bind and unbind api
------------------
+Internal bind and unbind API
+============================
 
 It is possible to enable an internal API which allows for binding and unbinding
 between identifiers and matrix IDs without any validation.
 This is open to abuse, so is disabled by
 default, and when it is enabled, is available only on a separate socket which
-is bound to 'localhost' by default.
+is bound to ``localhost`` by default.
 
 To enable it, configure the port in the config file. For example::
 
     [http]
     internalapi.http.port = 8091
 
+To change the address to which that API is bound, set the ``internalapi.http.bind_address`` configuration
+setting in the ``[http]`` section, for example::
+
+    [http]
+    internalapi.http.port = 8091
+    internalapi.http.bind_address = 192.168.0.18
+
+As already mentioned above, this is open to abuse, so make sure this address is not publicly accessible.
+
 To use bind::
 
     curl -XPOST 'http://localhost:8091/_matrix/identity/internal/bind' -H "Content-Type: application/json" -d '{"address": "matthew@arasphere.net", "medium": "email", "mxid": "@matthew:matrix.org"}'
@@ -101,8 +135,9 @@ To use unbind::
 The response has the same format as
 `/_matrix/identity/api/v1/3pid/unbind <https://matrix.org/docs/spec/identity_service/r0.3.0#deprecated-post-matrix-identity-api-v1-3pid-unbind>`_.
 
+
 Replication
 ===========
 
-It is possible to configure a mesh of sydents which replicate identity bindings
+It is possible to configure a mesh of Sydent instances which replicate identity bindings
 between each other. See `<docs/replication.md>`_.