Improve README and add docstrings

.gitignore

@@ -1,12 +1,16 @@
 *.pyc
-.idea
-.cache
-.tox
+*.pyo
+
 *.egg
 *.egg-info
+
+.cache
 .coverage
-/build/
+.idea
+.mypy_cache
+.pytest_cache
+.tox
+.venv
 
+/build/
 /dist/
-/.mypy_cache
-/.pytest_cache

.travis.yml

@@ -11,7 +11,10 @@ matrix:
   - python: '3.5'
     env: TOX_ENV=py35
   - python: '3.6'
-    env: TOX_ENV=py36,import-order,flake8,mypy
+    env: TOX_ENV=py36
+  - python: '3.7'
+    env: TOX_ENV=py37,import-order,flake8,mypy
+    dist: xenial
 cache:
   directories:
   - $HOME/.cache/pip

README.md

@@ -1,16 +1,40 @@
-# GraphQL-Server
+# GraphQL-Server-Core
 
 [![Build Status](https://travis-ci.org/graphql-python/graphql-server-core.svg?branch=master)](https://travis-ci.org/graphql-python/graphql-server-core) [![Coverage Status](https://coveralls.io/repos/graphql-python/graphql-server-core/badge.svg?branch=master&service=github)](https://coveralls.io/github/graphql-python/graphql-server-core?branch=master) [![PyPI version](https://badge.fury.io/py/graphql-server-core.svg)](https://badge.fury.io/py/graphql-server-core)
 
-GraphQL Server core package.
+GraphQL-Server-Core is a base library that serves as a helper
+for building GraphQL servers or integrations into existing web frameworks using
+[GraphQL-Core](https://github.com/graphql-python/graphql-core).
 
-## Integrations
+## Existing integrations built with GraphQL-Server-Core
 
-GraphQL Server powers the following integrations
+| Server integration | Package |
+|---|---|
+| Flask | [flask-graphql](https://github.com/graphql-python/flask-graphql/) |
+| Sanic |[sanic-graphql](https://github.com/graphql-python/sanic-graphql/) |
+| AIOHTTP | [aiohttp-graphql](https://github.com/graphql-python/aiohttp-graphql) |
+| WebOb (Pyramid, TurboGears) |  [webob-graphql](https://github.com/graphql-python/webob-graphql/) |
+| WSGI | [wsgi-graphql](https://github.com/moritzmhmk/wsgi-graphql) |
+| Responder | [responder.ext.graphql](https://github.com/kennethreitz/responder/blob/master/responder/ext/graphql.py) |
 
-| Server integration   |   Package |
-|---------------|-------------------|
-| Django        |  [graphene-django](https://github.com/graphql-python/graphene-django/)  |
-| Flask    |  [flask-graphql](https://github.com/graphql-python/flask-graphql/)  |
-| Sanic    |  [sanic-graphql](https://github.com/graphql-python/sanic-graphql/)  |
-| WebOb (Pyramid, Pylons)    |  [webob-graphql](https://github.com/graphql-python/webob-graphql/)  |
+## Other integrations using GraphQL-Core or Graphene
+
+| Server integration | Package |
+|---|---|
+| Django | [graphene-django](https://github.com/graphql-python/graphene-django/) |
+
+## Documentation
+
+The `graphql_server` package provides these three public helper functions:
+
+ * `run_http_query`
+ * `encode_execution_results`
+ * `laod_json_body`
+
+All functions in the package are annotated with type hints and docstrings,
+and you can build HTML documentation from these using `bin/build_docs`.
+
+You can also use one of the existing integrations listed above as
+blueprint to build your own integration or GraphQL server implementations.
+
+Please let us know when you have built something new, so we can list it here.

README.rst

@@ -1,26 +1,55 @@
-GraphQL-Server
-==============
+GraphQL-Server-Core
+===================
 
 |Build Status| |Coverage Status| |PyPI version|
 
-GraphQL Server core package.
+GraphQL-Server-Core is a base library that serves as a helper for
+building GraphQL servers or integrations into existing web frameworks
+using `GraphQL-Core <https://github.com/graphql-python/graphql-core>`__.
 
-Integrations
-------------
+Existing integrations built with GraphQL-Server-Core
+----------------------------------------------------
 
-GraphQL Server powers the following integrations
+=========================== ==========================================================================================================
+Server integration          Package
+=========================== ==========================================================================================================
+Flask                       `flask-graphql <https://github.com/graphql-python/flask-graphql/>`__
+Sanic                       `sanic-graphql <https://github.com/graphql-python/sanic-graphql/>`__
+AIOHTTP                     `aiohttp-graphql <https://github.com/graphql-python/aiohttp-graphql>`__
+WebOb (Pyramid, TurboGears) `webob-graphql <https://github.com/graphql-python/webob-graphql/>`__
+WSGI                        `wsgi-graphql <https://github.com/moritzmhmk/wsgi-graphql>`__
+Responder                   `responder.ext.graphql <https://github.com/kennethreitz/responder/blob/master/responder/ext/graphql.py>`__
+=========================== ==========================================================================================================
 
-+---------------------------+----------------------------------------------------------------------------+
-| Server integration        | Package                                                                    |
-+===========================+============================================================================+
-| Django                    | `graphene-django <https://github.com/graphql-python/graphene-django/>`__   |
-+---------------------------+----------------------------------------------------------------------------+
-| Flask                     | `flask-graphql <https://github.com/graphql-python/flask-graphql/>`__       |
-+---------------------------+----------------------------------------------------------------------------+
-| Sanic                     | `sanic-graphql <https://github.com/graphql-python/sanic-graphql/>`__       |
-+---------------------------+----------------------------------------------------------------------------+
-| WebOb (Pyramid, Pylons)   | `webob-graphql <https://github.com/graphql-python/webob-graphql/>`__       |
-+---------------------------+----------------------------------------------------------------------------+
+Other integrations using GraphQL-Core or Graphene
+-------------------------------------------------
+
+================== ========================================================================
+Server integration Package
+================== ========================================================================
+Django             `graphene-django <https://github.com/graphql-python/graphene-django/>`__
+================== ========================================================================
+
+Documentation
+-------------
+
+The ``graphql_server`` package provides these three public helper
+functions:
+
+-  ``run_http_query``
+-  ``encode_execution_results``
+-  ``laod_json_body``
+
+All functions in the package are annotated with type hints and
+docstrings, and you can build HTML documentation from these using
+``bin/build_docs``.
+
+You can also use one of the existing integrations listed above as
+blueprint to build your own integration or GraphQL server
+implementations.
+
+Please let us know when you have built something new, so we can list it
+here.
 
 .. |Build Status| image:: https://travis-ci.org/graphql-python/graphql-server-core.svg?branch=master
    :target: https://travis-ci.org/graphql-python/graphql-server-core

bin/build_docs

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# the documentation can be created from the docstrings
+# with pdoc (https://pdoc3.github.io/pdoc/)
+
+pdoc --html --overwrite --html-dir docs graphql_server

bin/convert_readme

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# the README can be converted from MarkDown to reST
+# with pandoc (https://pandoc.org/)
+
+pandoc README.md --from markdown --to rst -s -o README.rst