summaryrefslogtreecommitdiff
path: root/docs/index.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/index.rst')
-rw-r--r--docs/index.rst215
1 files changed, 215 insertions, 0 deletions
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..feb31c1
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,215 @@
+.. pykwalify documentation master file, created by
+ sphinx-quickstart on Sun Mar 6 16:03:21 2016.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to pykwalify's documentation!
+=====================================
+
+PyKwalify is a open source port of the kwalify lib and specification. The original source code was written in Java but this port is based on Python. The code is open source, and `available on github`_.
+
+.. _available on github: http://github.com/grokzen/pykwalify
+
+
+YAML/JSON validation library
+
+This framework is a port with alot added functionality of the java version of the framework kwalify that can be found at: http://www.kuwata-lab.com/kwalify/
+
+The source code can be found at: http://sourceforge.net/projects/kwalify/files/kwalify-java/0.5.1/
+
+The schema this library is base and extended from: http://www.kuwata-lab.com/kwalify/ruby/users-guide.01.html#schema
+
+
+
+Usage
+-----
+
+Create a data file. `Json` and `Yaml` formats are both supported.
+
+.. code-block:: yaml
+
+ - foo
+ - bar
+
+Create a schema file with validation rules.
+
+.. code-block:: yaml
+
+ type: seq
+ sequence:
+ - type: str
+
+Run validation from cli.
+
+.. code-block:: bash
+
+ pykwalify -d data.yaml -s schema.yaml
+
+
+
+Examples
+--------
+
+The documentation describes in detail how each keyword and type works and what is possible in each case.
+
+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.
+
+The files can be found here and it shows both schema/data combinations that will work and that will fail.
+
+ - `tests/files/success/`
+ - `tests/files/fail/`
+ - `tests/files/partial_schemas/`
+
+
+
+PyYaml and ruamel.yaml
+----------------------
+
+``PyYaml`` is the default installed yaml parser and ``ruamel.yaml`` is possible to install at the same time with the following command
+
+.. code-block:: bash
+
+ pip install 'pykwalify[ruamel]'
+
+ # 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.
+
+``PyYaml`` will still be the default parser becuase it is used more and is still considered the default ``YAML`` parser in the python world.
+
+Depending on how both libraries is developed, this can change in the future in any major update.
+
+
+
+UTF-8 and data encoding
+-----------------------
+
+If you have problems with unicode values not working properly when running pykwalify on python 2.7.x then try to add
+this environment variable to your execution and it might help to force UTF-8 encoding on all string objects.
+
+If this do not work please open up a issue with your schema and data that can be used to track down the problem in the source code.
+
+.. code-block:: bash
+
+ PYTHONIOENCODING=UTF-8 pykwalify ...
+
+
+
+Project details
+---------------
+
+.. |travis-master| image:: https://travis-ci.org/Grokzen/pykwalify.svg?branch=master
+ :target: https://travis-ci.org/Grokzen/pykwalify.svg?branch=master
+
+.. |travis-unstable| image:: https://travis-ci.org/Grokzen/pykwalify.svg?branch=unstable
+ :target: https://travis-ci.org/Grokzen/pykwalify.svg?branch=unstable
+
+.. |gitter-badge| image:: https://badges.gitter.im/Join Chat.svg
+ :target: https://gitter.im/Grokzen/pykwalify?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+
+.. |coveralls-badge| image:: https://coveralls.io/repos/github/Grokzen/pykwalify/badge.svg?branch=unstable
+ :target: https://coveralls.io/repos/github/Grokzen/pykwalify/badge.svg?branch=unstable
+
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| python support | 2.7, 3.3, 3.4, 3.5, 3.6, 3.7 |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Source | https://github.com/Grokzen/pykwalify |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Docs (Latest release) | http://pykwalify.readthedocs.io/en/master/ |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Docs (Unstable branch)| http://pykwalify.readthedocs.io/en/unstable/ |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Gitter (Free Chat) | |gitter-badge| |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Changelog | https://github.com/Grokzen/pykwalify/blob/unstable/docs/release-notes.rst |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Upgrade instructions | https://github.com/Grokzen/pykwalify/blob/unstable/docs/upgrade-instructions.rst |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Issues | https://github.com/Grokzen/pykwalify/issues |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Travis (master) | |travis-master| |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Travis (unstable) | |travis-unstable| |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Test coverage | |coveralls-badge| |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| pypi | https://pypi.python.org/pypi/pykwalify/ |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Open Hub | https://www.openhub.net/p/pykwalify |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| License | MIT https://github.com/Grokzen/pykwalify/blob/unstable/docs/license.rst |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Copyright | Copyright (c) 2013-2017 Johan Andersson |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| git repo | git clone git@github.com:Grokzen/pykwalify.git |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| install stable | pip install pykwalify |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| install dev | .. code-block:: bash |
+| | |
+| | $ git clone git@github.com:Grokzen/pykwalify.git pykwalify |
+| | $ cd ./pykwalify |
+| | $ virtualenv .venv |
+| | $ source .venv/bin/activate |
+| | $ pip install -r dev-requirements.txt |
+| | $ pip install -e . |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| required dependencies | | docopt >= 0.6.2 |
+| | | python-dateutil >= 2.4.2 |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| supported yml parsers | | PyYaml >= 3.11 |
+| | | ruamel.yaml >= 0.11.0 |
++-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+
+
+The Usage Guide
+---------------
+
+.. _validation-rules-docs:
+
+.. toctree::
+ :maxdepth: 2
+ :glob:
+
+ basics
+ validation-rules
+
+
+
+.. _partial-schemas-docs:
+
+.. toctree::
+ :maxdepth: 2
+ :glob:
+
+ partial-schemas
+
+
+
+.. _extensions-docs:
+
+.. toctree::
+ :maxdepth: 2
+ :glob:
+
+ extensions
+
+
+
+The Community Guide
+--------------------
+
+.. _community-guide:
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ testing
+ upgrade-instructions
+ release-notes
+ authors
+ license