Move subscription documentation into docs/

README.md

@@ -59,42 +59,6 @@ urlpatterns = [
 ]
 ```
 
-### Subscription Support
-
-The `graphene-django` project does not currently support GraphQL subscriptions out of the box. However, there are
-several community-driven modules for adding subscription support, and the GraphiQL interface provided by
-`graphene-django` supports subscriptions over websockets.
-
-To implement websocket-based support for GraphQL subscriptions, you'll need to:
-
-1. Install and configure [`django-channels`](https://channels.readthedocs.io/en/latest/installation.html).
-2. Install and configure<sup>1, 2</sup> a third-party module for adding subscription support over websockets. A few
-   options include:
-   - [`graphql-python/graphql-ws`](https://github.com/graphql-python/graphql-ws)
-   - [`datavance/django-channels-graphql-ws`](https://github.com/datadvance/DjangoChannelsGraphqlWs)
-   - [`jaydenwindle/graphene-subscriptions`](https://github.com/jaydenwindle/graphene-subscriptions)
-3. Ensure that your application (or at least your GraphQL endpoint) is being served via an ASGI protocol server like
-   `daphne` (built in to `django-channels`), [`uvicorn`](https://www.uvicorn.org/), or
-   [`hypercorn`](https://pgjones.gitlab.io/hypercorn/).
-
-> **<sup>1</sup> Note:** By default, the GraphiQL interface that comes with `graphene-django` assumes that you are
-> handling subscriptions at the same path as any other operation (i.e., you configured both `urls.py` and `routing.py`
-> to handle GraphQL operations at the same path, like `/graphql`).
->
-> If these URLs differ, GraphiQL will try to run your subscription over HTTP, which will produce an error. If you need
-> to use a different URL for handling websocket connections, you can configure `SUBSCRIPTION_PATH` in your
-> `settings.py`:
->
-> ```python
-> GRAPHENE = {
->     # ...
->     "SUBSCRIPTION_PATH": "/ws/graphql"  # The path you configured in `routing.py`, including a leading slash.
-> }
-> ```
-
-Once your application is properly configured to handle subscriptions, you can use the GraphiQL interface to test
-subscriptions like any other operation.
-
 ## Examples
 
 Here is a simple Django model:

docs/settings.rst

@@ -170,3 +170,18 @@ Default: ``None``
    GRAPHENE = {
       'DJANGO_CHOICE_FIELD_ENUM_CUSTOM_NAME': "myapp.utils.enum_naming"
    }
+
+
+``SUBSCRIPTION_PATH``
+--------------------------------------
+
+Define an alternative URL path where subscription operations should be routed.
+
+The GraphiQL interface will use this setting to intelligently route subscription operations. This is useful if you have more advanced infrastructure requirements that prevent websockets from being handled at the same path (e.g., a WSGI server listening at ``/graphql`` and an ASGI server listening at ``/ws/graphql``).
+
+Default: ``None``
+
+.. code:: python
+   GRAPHENE = {
+      'SUBSCRIPTION_PATH': "/ws/graphql"
+   }

docs/subscriptions.rst

@@ -0,0 +1,42 @@
+Subscription Support
+====================
+
+The ``graphene-django`` project does not currently support GraphQL subscriptions out of the box. However, there are
+several community-driven modules for adding subscription support, and the GraphiQL interface provided by
+``graphene-django`` supports subscriptions over websockets.
+
+To implement websocket-based support for GraphQL subscriptions, you’ll need to do the following:
+
+1. Install and configure `django-channels <https://channels.readthedocs.io/en/latest/installation.html>`_.
+2. Install and configure* a third-party module for adding subscription support over websockets. A few options include:
+
+   -  `graphql-python/graphql-ws <https://github.com/graphql-python/graphql-ws>`_
+   -  `datavance/django-channels-graphql-ws <https://github.com/datadvance/DjangoChannelsGraphqlWs>`_
+   -  `jaydenwindle/graphene-subscriptions <https://github.com/jaydenwindle/graphene-subscriptions>`_
+
+3. Ensure that your application (or at least your GraphQL endpoint) is being served via an ASGI protocol server like
+   daphne (built in to ``django-channels``), `uvicorn <https://www.uvicorn.org/>`_, or
+   `hypercorn <https://pgjones.gitlab.io/hypercorn/>`_.
+
+..
+
+   *** Note:** By default, the GraphiQL interface that comes with
+   ``graphene-django`` assumes that you are handling subscriptions at
+   the same path as any other operation (i.e., you configured both
+   ``urls.py`` and ``routing.py`` to handle GraphQL operations at the
+   same path, like ``/graphql``).
+
+   If these URLs differ, GraphiQL will try to run your subscription over
+   HTTP, which will produce an error. If you need to use a different URL
+   for handling websocket connections, you can configure
+   ``SUBSCRIPTION_PATH`` in your ``settings.py``:
+
+   .. code:: python
+
+      GRAPHENE = {
+          # ...
+          "SUBSCRIPTION_PATH": "/ws/graphql"  # The path you configured in `routing.py`, including a leading slash.
+      }
+
+Once your application is properly configured to handle subscriptions, you can use the GraphiQL interface to test
+subscriptions like any other operation.