python-gitlab
diff --git a/‎docs/api-usage.rst
+4-4 b/‎docs/api-usage.rst
+4-4
diff --git a/‎docs/cli-usage.rst
+3-3 b/‎docs/cli-usage.rst
+3-3
diff --git a/‎docs/graphql-api-usage.rst
+55 b/‎docs/graphql-api-usage.rst
+55
diff --git a/‎docs/index.rst
+1 b/‎docs/index.rst
+1
diff --git a/‎gitlab/__init__.py
+1-1 b/‎gitlab/__init__.py
+1-1
@@ -1,8 +1,8 @@
-############################
-Getting started with the API
-############################
+##################
+Using the REST API
+##################
 
-python-gitlab only supports GitLab API v4.
+python-gitlab currently only supports v4 of the GitLab REST API.
 
 ``gitlab.Gitlab`` class
 =======================
 
@@ -1,6 +1,6 @@
-############################
-Getting started with the CLI
-############################
+#############
+Using the CLI
+#############
 
 ``python-gitlab`` provides a :command:`gitlab` command-line tool to interact
 with GitLab servers.
 
@@ -0,0 +1,55 @@
+#####################
+Using the GraphQL API
+#####################
+
+python-gitlab provides basic support for executing GraphQL queries and mutations.
+
+.. danger::
+
+   The GraphQL client is experimental and only provides basic support.
+   It does not currently support pagination, obey rate limits,
+   or attempt complex retries. You can use it to build simple queries
+
+   It is currently unstable and its implementation may change. You can expect a more
+   mature client in one of the upcoming major versions.
+
+The ``gitlab.GraphQLGitlab`` class
+==================================
+
+As with the REST client, you connect to a GitLab instance by creating a ``gitlab.GraphQLGitlab`` object:
+
+.. code-block:: python
+
+   import gitlab
+
+   # anonymous read-only access for public resources (GitLab.com)
+   gl = gitlab.GraphQLGitlab()
+
+   # anonymous read-only access for public resources (self-hosted GitLab instance)
+   gl = gitlab.GraphQLGitlab('https://gitlab.example.com')
+
+   # private token or personal token authentication (GitLab.com)
+   gl = gitlab.GraphQLGitlab(private_token='JVNSESs8EwWRx5yDxM5q')
+
+   # private token or personal token authentication (self-hosted GitLab instance)
+   gl = gitlab.GraphQLGitlab(url='https://gitlab.example.com', private_token='JVNSESs8EwWRx5yDxM5q')
+
+   # oauth token authentication
+   gl = gitlab.GraphQLGitlab('https://gitlab.example.com', oauth_token='my_long_token_here')
+
+Sending queries
+===============
+
+Get the result of a simple query:
+
+.. code-block:: python
+
+    query = """{
+        query {
+          currentUser {
+            name
+          }
+        }
+    """
+
+    result = gl.execute(query)
@@ -7,6 +7,7 @@
    cli-usage
    api-usage
    api-usage-advanced
+   graphql-api-usage
    cli-examples
    api-objects
    api/gitlab
 
@@ -29,7 +29,7 @@
     __title__,
     __version__,
 )
-from gitlab.client import Gitlab, GitlabList  # noqa: F401
+from gitlab.client import Gitlab, GitlabList, GraphQLGitlab  # noqa: F401
 from gitlab.exceptions import *  # noqa: F401,F403
 
 warnings.filterwarnings("default", category=DeprecationWarning, module="^gitlab")
Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@`
`29`	`29`	`__title__,`
`30`	`30`	`__version__,`
`31`	`31`	`)`
`32`		`-from gitlab.client import Gitlab, GitlabList # noqa: F401`
	`32`	`+from gitlab.client import Gitlab, GitlabList, GraphQLGitlab # noqa: F401`
`33`	`33`	`from gitlab.exceptions import * # noqa: F401,F403`
`34`	`34`
`35`	`35`	`warnings.filterwarnings("default", category=DeprecationWarning, module="^gitlab")`