chore: generate docs with sphinx (#117)

* chore: generate docs with sphinx

* chore: avoid documenting private members

* chore: add docs to manifiest

* chore: manually document every class on transport

* Write docs in sphinx rst format

* fix manifest

* Improve classes reference documentation

Co-authored-by: Hanusz Leszek <[email protected]>

Author: KingDarBoja

MANIFEST.in

@@ -13,7 +13,10 @@ include tox.ini
 include scripts/gql-cli
 
 recursive-include tests *.py *.graphql *.cnf *.yaml *.pem
+recursive-include docs *.txt *.rst conf.py Makefile make.bat *.jpg *.png *.gif
+recursive-include docs/code_examples *.py
 
+prune docs/_build
 prune gql-checker
 
 global-exclude *.py[co] __pycache__

Makefile

@@ -1,4 +1,4 @@
-.PHONY: clean tests
+.PHONY: clean tests docs
 
 dev-setup:
 	python pip install -e ".[test]"
@@ -16,6 +16,10 @@ check:
 	mypy gql tests
 	check-manifest
 
+docs:
+	rm -rf ./docs/_build
+	cd docs; make html
+
 clean:
 	find . -name "*.pyc" -delete
 	find . -name "__pycache__" | xargs -I {} rm -rf {}
@@ -26,4 +30,5 @@ clean:
 	rm -rf ./gql.egg-info
 	rm -rf ./dist
 	rm -rf ./build
+	rm -rf ./docs/_build
 	rm -f ./.coverage

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/advanced/async_advanced_usage.rst

@@ -0,0 +1,57 @@
+.. _async_advanced_usage:
+
+Async advanced usage
+====================
+
+It is possible to send multiple GraphQL queries (query, mutation or subscription) in parallel,
+on the same websocket connection, using asyncio tasks.
+
+In order to retry in case of connection failure, we can use the great `backoff`_ module.
+
+.. code-block:: python
+
+    # First define all your queries using a session argument:
+
+    async def execute_query1(session):
+        result = await session.execute(query1)
+        print(result)
+
+    async def execute_query2(session):
+        result = await session.execute(query2)
+        print(result)
+
+    async def execute_subscription1(session):
+        async for result in session.subscribe(subscription1):
+            print(result)
+
+    async def execute_subscription2(session):
+        async for result in session.subscribe(subscription2):
+            print(result)
+
+    # Then create a couroutine which will connect to your API and run all your queries as tasks.
+    # We use a `backoff` decorator to reconnect using exponential backoff in case of connection failure.
+
+    @backoff.on_exception(backoff.expo, Exception, max_time=300)
+    async def graphql_connection():
+
+        transport = WebsocketsTransport(url="wss://YOUR_URL")
+
+        client = Client(transport=transport, fetch_schema_from_transport=True)
+
+        async with client as session:
+            task1 = asyncio.create_task(execute_query1(session))
+            task2 = asyncio.create_task(execute_query2(session))
+            task3 = asyncio.create_task(execute_subscription1(session))
+            task4 = asyncio.create_task(execute_subscription2(session))
+
+            await asyncio.gather(task1, task2, task3, task4)
+
+    asyncio.run(graphql_connection())
+
+Subscriptions tasks can be stopped at any time by running
+
+.. code-block:: python
+
+    task.cancel()
+
+.. _backoff: https://github.com/litl/backoff

docs/advanced/dsl_module.rst

@@ -0,0 +1,34 @@
+Compose queries dynamically
+===========================
+
+Instead of providing the GraphQL queries as a Python String, it is also possible to create GraphQL queries dynamically.
+Using the DSL module, we can create a query using a Domain Specific Language which is created from the schema.
+
+.. code-block:: python
+
+    from gql.dsl import DSLSchema
+
+    client = Client(schema=StarWarsSchema)
+    ds = DSLSchema(client)
+
+    query_dsl = ds.Query.hero.select(
+        ds.Character.id,
+        ds.Character.name,
+        ds.Character.friends.select(ds.Character.name,),
+    )
+
+will create a query equivalent to:
+
+.. code-block:: python
+
+    hero {
+      id
+      name
+      friends {
+        name
+      }
+    }
+
+.. warning::
+
+    Please note that the DSL module is still considered experimental in GQL 3 and is subject to changes

docs/advanced/index.rst

@@ -0,0 +1,9 @@
+Advanced
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   async_advanced_usage
+   local_schema
+   dsl_module

docs/advanced/local_schema.rst

@@ -0,0 +1,25 @@
+Execution on a local schema
+===========================
+
+It is also possible to execute queries against a local schema (so without a transport), even
+if it is not really useful except maybe for testing.
+
+.. code-block:: python
+
+    from gql import gql, Client
+
+    from .someSchema import SampleSchema
+
+    client = Client(schema=SampleSchema)
+
+    query = gql('''
+        {
+          hello
+        }
+    ''')
+
+    result = client.execute(query)
+
+See `tests/starwars/test_query.py`_ for an example
+
+.. _tests/starwars/test_query.py: https://github.com/graphql-python/gql/blob/master/tests/starwars/test_query.py

docs/async/async_intro.rst

@@ -0,0 +1,18 @@
+On previous versions of GQL, the code was `sync` only , it means that when you ran
+`execute` on the Client, you could do nothing else in the current Thread and had to wait for
+an answer or a timeout from the backend to continue. The only http library was `requests`, allowing only sync usage.
+
+From the version 3 of GQL, we support `sync` and `async` :ref:`transports <transports>` using `asyncio`_.
+
+With the :ref:`async transports <async_transports>`, there is now the possibility to execute GraphQL requests
+asynchronously, :ref:`allowing to execute multiple requests in parallel if needed <async_advanced_usage>`.
+
+If you don't care or need async functionality, it is still possible, with :ref:`async transports <async_transports>`,
+to run the `execute` or `subscribe` methods directly from the Client
+(as described in the :ref:`Basic Usage <basic_usage>` example) and GQL will execute the request
+in a synchronous manner by running an asyncio event loop itself.
+
+This won't work though if you already have an asyncio event loop running. In that case you should use
+:ref:`Async Usage <async_usage>`
+
+.. _asyncio: https://docs.python.org/3/library/asyncio.html

docs/async/async_usage.rst

@@ -0,0 +1,17 @@
+.. _async_usage:
+
+Async Usage
+===========
+
+If you use an :ref:`async transport <async_transports>`, you can use GQL asynchronously using `asyncio`_.
+
+* put your code in an asyncio coroutine (method starting with :code:`async def`)
+* use :code:`async with client as session:` to connect to the backend and provide a session instance
+* use the :code:`await` keyword to execute requests: :code:`await session.execute(...)`
+* then run your coroutine in an asyncio event loop by running :code:`asyncio.run`
+
+Example:
+
+.. literalinclude:: ../code_examples/aiohttp_async.py
+
+.. _asyncio: https://docs.python.org/3/library/asyncio.html

docs/async/index.rst

@@ -0,0 +1,10 @@
+Async vs Sync
+=============
+
+.. include:: async_intro.rst
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   async_usage