Add Usage section, Update section pyyaml and ruamel.yaml

docs/index.rst

@@ -21,67 +21,65 @@ The schema this library is base and extended from: http://www.kuwata-lab.com/kwa
 
 
 
-Installation
-------------
+Usage
+-----
 
-Latest stable release from pypi
+Create a data file. `Json` and `Yaml` formats are both supported.
 
-.. code-block:: bash
-
-    $ pip install pykwalify
+.. code-block:: yaml
 
-or from source
+   - foo
+   - bar
 
-.. code-block:: bash
+Create a schema file with validation rules.
 
-    $ python setup.py install
+.. code-block:: yaml
 
+   type: seq
+   sequence:
+     - type: str
 
+Run validation from cli.
 
-PyYaml and ruamel.yaml
-----------------------
+.. code-block:: bash
 
-In release ``1.6.0`` ``PyYaml`` will be deprecated in favor of ``ruamel.yaml``.
+   pykwalify -d data.yaml -s schema.yaml
 
-``PyYaml`` is still the default installed one but it will removed in release 1.7.0 and ``ruamel.yaml`` will be the new default yaml parser lib from that release and forward.
 
-This decision was based on the following thread in the `PyYaml` repo https://bitbucket.org/xi/pyyaml/issues/59/has-this-project-been-abandoned
 
-Install it for production:
+Examples
+--------
 
-.. code-block:: bash
+The documentation describes in detail how each keyword and type works and what is possible in each case.
 
-  pip install 'pykwalify[ruamel]'
+But there is a lot of real world examples that can be found in the test data/files. It shows alot of examples of how all keywords and types work in practise and in combination with eachother.
 
-or for development:
+The files can be found here and it shows both schema/data combinations that will work and that will fail.
 
-.. code-block:: bash
+ - `tests/files/success/`
+ - `tests/files/fail/`
+ - `tests/files/partial_schemas/`
 
-  pip install -e '.[ruamel]'
 
 
+PyYaml and ruamel.yaml
+----------------------
 
-Runtime Dependencies
---------------------
+``PyYaml`` is the default installed yaml parser and ``ruamel.yaml`` is possible to install at the same time with the following command
 
- - docopt >= 0.6.2
- - PyYaml >= 3.11
- - python-dateutil >= 2.4.2
+.. code-block:: bash
 
-Optional dependencies:
+  pip install 'pykwalify[ruamel]'
 
- - ruamel.yaml >= 0.11.0
+  # or for development:
 
+  pip install -e '.[ruamel]'
 
+``ruamel.yaml`` will however be used if both is installed becuase it is more up to date and includes the YAML 1.2 specification that ``PyYaml`` do not support.
 
-Supported python version
-------------------------
+``PyYaml`` will still be the default parser becuase it is used more and is still considered the default ``YAML`` parser in the python world.
 
- - Python 2.7
- - Python 3.3
- - Python 3.4
- - Python 3.5
- - Python 3.6 (Experimental, allowed to fail travis testing)
+Depending on how both libraries is developed, this can change in the future in any major update.