Added GraphQL support documentation

docs/graphql.rst

@@ -0,0 +1,54 @@
+GraphQL support
+===============
+
+`Hiku` is trying to be simple so it doesn't support all the `GraphQL`
+features.
+
+In order to parse `GraphQL` queries you will need to install `graphql-core`
+library:
+
+.. code-block:: shell
+
+    pip install graphql-core
+
+or install `Hiku` library with extras:
+
+.. code-block:: shell
+
+    pip install hiku[graphql]
+
+**Supported features**
+
+- documents with single query operation
+- selection sets
+- fields with arguments
+
+**Probably will be supported**
+
+- field aliases
+
+**Unsupported (intentionally)**
+
+- mutations and other possible non-query operations
+- multiple operations per document
+- all the fragments-related features
+- introspection
+- directives
+- interfaces
+- variables
+- unions
+- enums
+
+Reading GraphQL queries
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Minimal graph definition:
+
+.. literalinclude:: test_graphql.py
+    :lines: 9-23
+
+`GraphQL` query execution:
+
+.. literalinclude:: test_graphql.py
+    :lines: 29-32
+    :dedent: 4

docs/index.rst

@@ -77,6 +77,7 @@ and transform data from low-level graph.
     :maxdepth: 2
 
     guide/index
+    graphql
     reference/index
     changelog/index
 

docs/test_graphql.py

@@ -0,0 +1,32 @@
+# prerequisites
+from datetime import datetime as _datetime
+
+from tests.base import patch, Mock
+
+_NOW = _datetime(2015, 10, 21, 7, 28)
+
+# example
+from datetime import datetime
+
+from hiku.graph import Graph, Root, Field
+from hiku.engine import Engine
+from hiku.result import denormalize
+from hiku.executors.sync import SyncExecutor
+from hiku.readers.graphql import read
+
+GRAPH = Graph([
+    Root([
+        Field('now', None, lambda _: [datetime.now().isoformat()]),
+    ]),
+])
+
+hiku_engine = Engine(SyncExecutor())
+
+@patch('{}.datetime'.format(__name__))
+def test(dt):
+    dt.now = Mock(return_value=_NOW)
+
+    query = read('{ now }')
+    result = hiku_engine.execute(GRAPH, query)
+    simple_result = denormalize(GRAPH, result, query)
+    assert simple_result == {'now': '2015-10-21T07:28:00'}