Add separate interfaces docs

docs/general-usage/graphql-types.rst

@@ -9,84 +9,6 @@ detail below.
 An existing understanding of GraphQL types will help here.
 
 
-PageInterface
-^^^^^^^^^^^^^
-
-The default GraphQL interface for all Wagtail Page-derived models.
-
-This is accessible through the ``pages`` or ``page`` field on the root query type.
-
-The interface exposes the following fields, following the Wagtail Page model fields and properties:
-
-.. code-block:: graphql
-
-    id: ID
-    url: String
-    slug: String
-    depth: Int
-    pageType: String
-    title: String
-    seoTitle: String
-    seoDescription: String
-    showInMenus: Boolean
-    contentType: String
-    parent: PageInterface
-    children(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
-    siblings(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
-    nextSiblings(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
-    previousSiblings(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
-    descendants(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
-    ancestors(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
-
-
-Any custom ``graphql_fields`` added to your specific Page models will be available here via the 'on' spread operator and
-the name of the model:
-
-.. code-block:: graphql
-
-    query {
-        pages {
-            ...on BlogPage {
-                the_custom_field
-            }
-        }
-    }
-
-You can change the default ``PageInterface`` to your own interface by changing the
-:ref:`PAGE_INTERFACE<page interface settings>` setting.
-
-As mentioned above there is both a plural ``pages`` and singular ``page``
-field on the root Query type that returns a ``PageInterface``.
-
-The plural ``pages`` field (as do all plural fields)
-accepts the following arguments:
-
-.. code-block:: graphql
-
-    id: ID
-    limit: PositiveInt
-    offset: PositiveInt
-    order: String
-    searchQuery: String
-    contentType: String           #  comma separated list of content types in app.Model notation
-    inSite: Boolean
-    ancestor: PositiveInt         # ID of ancestor page to restrict results to
-    parent: PositiveInt           # ID of parent page to restrict results to
-
-
-The singular ``page`` field accepts the following arguments:
-
-.. code-block:: graphql
-
-    id: ID                        # Can be used on it's own
-    slug: String                  # Can be used on it's own
-    urlPath: String               # Can be used on it's own
-    token: String                 # Must be used with one of the others. Usually contentType
-    contentType: String           # Can be used on it's own
-    inSite: Boolean               # Can be used on it's own
-
-
-
 ImageObjectType
 ^^^^^^^^^^^^^^^
 

docs/general-usage/index.rst

@@ -6,6 +6,7 @@ General Usage
 
     graphql-types
     model-types
+    interfaces
     decorators
     hooks
     middleware

docs/general-usage/interfaces.rst

@@ -0,0 +1,163 @@
+Interfaces
+==========
+
+Out of the box, Grapple generates the schema with the following GraphQL interfaces:
+
+- ``PageInterface` for Wagtail ``Page`` models
+- ``StreamFieldInterface`` for Wagtail ``StreamField`` block models
+
+``PageInterface``
+-----------------
+
+The default GraphQL interface for all Wagtail ``Page``-derived models.
+
+This is accessible through the ``pages`` or ``page`` field on the root query type.
+
+The interface exposes the following fields, following the Wagtail Page model fields and properties:
+
+.. code-block:: graphql
+
+    id: ID
+    url: String
+    slug: String
+    depth: Int
+    pageType: String
+    title: String
+    seoTitle: String
+    seoDescription: String
+    showInMenus: Boolean
+    contentType: String
+    parent: PageInterface
+    children(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
+    siblings(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
+    nextSiblings(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
+    previousSiblings(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
+    descendants(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
+    ancestors(limit: PositiveInt, offset: PositiveInt, order: String, searchQuery: String, id: ID): [PageInterface]
+
+
+Any custom ``graphql_fields`` added to your specific Page models will be available here via the 'on' spread operator and
+the name of the model:
+
+.. code-block:: graphql
+
+    query {
+        pages {
+            ...on BlogPage {
+                the_custom_field
+            }
+        }
+    }
+
+You can change the default ``PageInterface`` to your own interface by changing the
+:ref:`PAGE_INTERFACE<page interface settings>` setting.
+
+As mentioned above there is both a plural ``pages`` and singular ``page``
+field on the root Query type that returns a ``PageInterface``.
+
+The plural ``pages`` field (as do all plural fields)
+accepts the following arguments:
+
+.. code-block:: graphql
+
+    id: ID
+    limit: PositiveInt
+    offset: PositiveInt
+    order: String
+    searchQuery: String
+    contentType: String           #  comma separated list of content types in app.Model notation
+    inSite: Boolean
+    ancestor: PositiveInt         # ID of ancestor page to restrict results to
+    parent: PositiveInt           # ID of parent page to restrict results to
+
+
+The singular ``page`` field accepts the following arguments:
+
+.. code-block:: graphql
+
+    id: ID                        # Can be used on it's own
+    slug: String                  # Can be used on it's own
+    urlPath: String               # Can be used on it's own
+    token: String                 # Must be used with one of the others. Usually contentType
+    contentType: String           # Can be used on it's own
+    inSite: Boolean               # Can be used on it's own
+
+
+
+``StreamFieldInterface``
+------------------------
+
+.. code-block:: graphql
+
+    id: ID
+    blockType: String!
+    field: String!
+    rawValue: String!
+
+Note that blocks subclassing `StreamBlock <https://docs.wagtail.org/en/stable/topics/streamfield.html#streamblock>`_
+and `StructBlock <https://docs.wagtail.org/en/stable/topics/streamfield.html#structblock>`_ have an additional property
+in the interface:
+
+.. code-block:: graphql
+
+    blocks: [StreamFieldInterface!]!  # a list of blocks in the StreamBlock or StructBlock
+
+
+
+Adding your own interfaces
+--------------------------
+
+To add your own interfaces to your model, define the ``graphql_interfaces`` attribute on it. The attribute should be
+a tuple of interfaces to add to the model.
+
+Given the following example interface:
+
+.. code-block:: python
+
+    # interfaces.py
+    from .interfaces import CustomInterface
+
+
+    class CustomInterface(graphene.Interface):
+        custom_field = graphene.String()
+
+you could add it to your Page model like so:
+
+.. code-block:: python
+
+    from wagtail.models import Page
+
+
+    class MyPage(Page):
+        # ...
+
+        graphql_interfaces = (CustomInterface,)
+
+or any Django model:
+
+.. code-block:: python
+
+    # models.py
+    from django.db import models
+
+
+    class MyModel(models.Model):
+        # ...
+
+        graphql_interfaces = (CustomInterface,)
+
+
+or a ``StreamField`` block:
+
+.. code-block:: python
+
+    # blocks.py
+    from wagtail.core import blocks
+
+
+    class MyStructBlock(blocks.StructBlock):
+        # ...
+
+        graphql_interfaces = (CustomInterface,)
+
+The provided interfaces will be added to the base interfaces for the model.