Start on mutations

Paul Hallett · Paul Hallett · commit 0f7844bb64d7 · 2019-04-30T16:50:13.000+01:00
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,7 +3,11 @@ Graphene-Django
 
 Welcome to the Graphene-Django docs.
 
-First time? We recommend you start with the installation guide and then read the basic tutorial.
+Graphene-Django is built on top of `Graphene <https://docs.graphene-python.org/en/latest/>`__.
+Graphene-Django provides some additional abstractions that make it easy to add GraphQL functionality to your Django project.
+
+First time? We recommend you start with the installation guide to get set up and the basic tutorial.
+It is worth reading the `core graphene docs <https://docs.graphene-python.org/en/latest/>`__ to familiarize yourself with the basic utilities.
 
 Core tenants
 ------------
@@ -22,7 +26,6 @@ For more advanced use, check out the Relay tutorial.
    schema
    queries
    mutations
-   relay
    filtering
    authorization
    debug
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -17,7 +17,7 @@ Installation
 
     pip install graphene-django
 
-**We strongly recommend pinning against a specific version of graphene-django as new versions could introduce breaking changes to your project.**
+**We strongly recommend pinning against a specific version of Graphene-Django as new versions could introduce breaking changes to your project.**
 
 Add ``graphene_django`` to the ``INSTALLED_APPS`` in the ``settings.py`` file of your Django project:
 
@@ -42,6 +42,8 @@ We need to add a graphql URL to the ``urls.py`` of your Django project:
         url(r'^graphql', GraphQLView.as_view(graphiql=True)),
     ]
 
+(Changed ``graphiql=True`` to ``graphiql=False`` if you do not want to use the graphiQL API browser.)
+
 Finally, define the schema location for Graphene in the ``settings.py`` file of your Django project:
 
 .. code:: python
diff --git a/docs/mutations.rst b/docs/mutations.rst
@@ -1,2 +1,61 @@
 Mutations
-=========
+=========
+
+Introduction
+------------
+
+Mutations allow you to `mutate` data.
+
+With Graphene-Django we can take advantage of pre-existing Django features to
+quickly build CRUD functionality, while still using the core `graphene mutation <https://docs.graphene-python.org/en/latest/types/mutations/>`__
+features to add custom mutations to a Django project.
+
+Simple example
+--------------
+
+.. code:: python
+
+    import graphene
+
+    from graphene_django import DjangoObjectType
+
+    from .models import Question
+
+
+    class QuestionType(DjangoObjectType):
+        class Meta:
+            model = Question
+
+
+    class QuestionMutation(graphene.Mutation):
+        class Input:
+            # The input arguments for this mutation
+            text = graphene.String(required=True)
+            id = graphene.ID()
+
+        # The class attributes define the response of the mutation
+        question = graphene.Field(QuestionType)
+
+        def mutate(self info, text, id):
+            question = Question.objects.get(pk=id)
+            question.text = text
+            question.save()
+            # Notice we return an instance of this mutation
+            return QuestionMutation(question=question)
+
+
+    class Mutation:
+        update_question = QuestionMutation.Field()
+
+
+
+Relay
+-----
+
+
+Django Forms
+------------
+
+
+Django REST Framework
+---------------------
diff --git a/docs/queries.rst b/docs/queries.rst
@@ -1,22 +1,17 @@
-Queries
-=======
+Queries & ObjectTypes
+=====================
 
 Introduction
 ------------
 
-The core functionality of GraphQL is to make queries and get data back.
+The core functionality of GraphQL is to make queries in order to get data.
 
 Graphene-Django ships with a special ``DjangoObjectType`` that automagically transforms a Django Model
-into a Query object for you.
-
-In the world of Django; a query object can be considered a Django Model, and a query field a
-Django Model field. However you are not limited to just Django Models with Graphene Django - you can use the standard
-``ObjectType`` to create custom fields or to provide an abstraction between your internal
-Django models and your external API.
+into a ``ObjectType`` for you.
 
 
 Full example
-------------
+~~~~~~~~~~~~
 
 .. code:: python
 
@@ -49,7 +44,7 @@ Full example
 Fields
 ------
 
-By default, ``DjangoObjectType`` will present all fields on a Model through graphQL.
+By default, ``DjangoObjectType`` will present all fields on a Model through GraphQL.
 If you don't want to do this you can change this by setting either ``only_fields`` and ``exclude_fields``.
 
 only_fields
@@ -101,13 +96,14 @@ Default QuerySet
 -----------------
 
 If you are using ``DjangoObjectType`` you can define a custom `get_queryset` method.
-Use this to control filtering on the object level instead of the **resolve method** level.
+Use this to control filtering on the ObjectType level instead of the Query object level.
 
 .. code:: python
 
     from graphene_django.types import DjangoObjectType
     from .models import Question
 
+
     class QuestionType(DjangoObjectType):
         class Meta:
             model = Question
@@ -159,9 +155,9 @@ Info
 ~~~~
 
 The ``info`` argument passed to all resolve methods holds some useful information.
-For graphene-django, the ``info.context`` object is the ``HTTPRequest`` object
+For Graphene-Django, the ``info.context`` object is the ``HTTPRequest`` object
 that would be familiar to any Django developer. This gives you the full functionality
-of Django's `HTTPRequest` in your resolve methods, such as checking for authenticated users:
+of Django's ``HTTPRequest`` in your resolve methods, such as checking for authenticated users:
 
 .. code:: python
 
@@ -173,6 +169,64 @@ of Django's `HTTPRequest` in your resolve methods, such as checking for authenti
             return Question.objects.none()
 
 
+Plain ObjectTypes
+-----------------
+
+With Graphene-Django you are not limited to just Django Models - you can use the standard
+``ObjectType`` to create custom fields or to provide an abstraction between your internal
+Django models and your external API.
+
+.. code:: python
+
+    import graphene
+    from .models import Question
+
+
+    class MyQuestion(graphene.ObjectType):
+        text = graphene.String()
+
+
+    class Query:
+        question = graphene.Field(MyQuestion, question_id=graphene.String())
+
+        def resolve_question(self, info, question_id):
+            question = Question.objects.get(pk=question_id)
+            return MyQuestion(
+                text=question.question_text
+            )
+
 For more information and more examples, please see the `core object type documentation <https://docs.graphene-python.org/en/latest/types/objecttypes/>`__.
 
-For additional features such as automatic filtering and pagination, please see the Relay tutorial.
+
+Relay
+-----
+
+`Relay <http://docs.graphene-python.org/en/latest/relay/>`__ with Graphene-Django gives us some additional features:
+
+- Pagination and slicing.
+- An abstract ``id`` value which contains enough info for the server to know its type and its id.
+
+Full example
+~~~~~~~~~~~~
+
+.. code:: python
+
+    from graphene import relay
+    from graphene_django import DjangoObjectType
+    from .models import Question
+
+
+    class QuestionType(DjangoObjectType):
+        class Meta:
+            model = Question
+            interaces = (relay.Node,)
+
+
+    class QuestionConnection(relay.Connection):
+        class Meta:
+            node = QuestionType
+
+
+    class Query:
+        question = graphene.Field(QuestionType)
+        questions = relay.ConnectionField(QuestionConnection)
diff --git a/docs/schema.rst b/docs/schema.rst
@@ -16,7 +16,7 @@ The ``graphene.Schema`` object describes your data model, and provides a GraphQL
     schema = graphene.Schema(query=Query, mutation=Mutation)
 
 
-This schema on it's own does nothing, but it is ready to accept new Query or Mutation fields that you create.
+This schema does nothing like this, but it is ready to accept new Query or Mutation fields that you create.
 
 
 Adding to the schema
@@ -31,10 +31,16 @@ If you have defined a ``Query`` or ``Mutation`` you can register them with the s
     import my_app.schema.Query
     import my_app.schema.Mutation
 
-    class Query(my_app.schema.Query, graphene.ObjectType):
+    class Query(
+        my_app.schema.Query, # Add your Query objects here
+        graphene.ObjectType
+    ):
         pass
 
-    class Mutation(my_app.schema.Mutation, graphene.ObjectType):
+    class Mutation(
+        my_app.schema.Mutation, # Add your Mutation objects here
+        graphene.ObjectType
+    ):
         pass
 
     schema = graphene.Schema(query=Query, mutation=Mutation)
