chore Fix docs sphinx nitpick warnings - adding intersphinx_mapping (#515)

Author: leszekhanusz

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -n
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

docs/code_examples/fastapi_async.py

@@ -10,6 +10,7 @@
 
 from fastapi import FastAPI, HTTPException
 from fastapi.responses import HTMLResponse
+
 from gql import Client, gql
 from gql.transport.aiohttp import AIOHTTPTransport
 

docs/conf.py

@@ -34,6 +34,7 @@
 extensions = [
     'sphinxarg.ext',
     'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
     'sphinx_rtd_theme'
 ]
 
@@ -77,3 +78,52 @@
     'show-inheritance': True
 }
 autosummary_generate = True
+
+# -- Intersphinx configuration ---------------------------------------------
+intersphinx_mapping = {
+    'aiohttp': ('https://docs.aiohttp.org/en/stable/', None),
+    'graphql': ('https://graphql-core-3.readthedocs.io/en/latest/', None),
+    'multidict': ('https://multidict.readthedocs.io/en/stable/', None),
+    'python': ('https://docs.python.org/3/', None),
+    'requests': ('https://requests.readthedocs.io/en/latest/', None),
+    'websockets': ('https://websockets.readthedocs.io/en/11.0.3/', None),
+    'yarl': ('https://yarl.readthedocs.io/en/stable/', None),
+}
+
+nitpick_ignore = [
+    # graphql-core: should be fixed
+    ('py:class', 'graphql.execution.execute.ExecutionResult'),
+    ('py:class', 'Source'),
+    ('py:class', 'GraphQLSchema'),
+
+    # asyncio: should be fixed
+    ('py:class', 'asyncio.locks.Event'),
+
+    # aiohttp: should be fixed
+    ('py:class', 'aiohttp.client_reqrep.Fingerprint'),
+    ('py:class', 'aiohttp.helpers.BasicAuth'),
+
+    # multidict: should be fixed
+    ('py:class', 'multidict._multidict.CIMultiDictProxy'),
+    ('py:class', 'multidict._multidict.CIMultiDict'),
+    ('py:class', 'multidict._multidict.istr'),
+
+    # websockets: first bump websockets version
+    ('py:class', 'websockets.datastructures.SupportsKeysAndGetItem'),
+    ('py:class', 'websockets.typing.Subprotocol'),
+
+    # httpx: no sphinx docs yet https://github.com/encode/httpx/discussions/3091
+    ('py:class', 'httpx.AsyncClient'),
+    ('py:class', 'httpx.Client'),
+    ('py:class', 'httpx.Headers'),
+
+    # botocore: no sphinx docs
+    ('py:class', 'botocore.auth.BaseSigner'),
+    ('py:class', 'botocore.awsrequest.AWSRequest'),
+    ('py:class', 'botocore.credentials.Credentials'),
+    ('py:class', 'botocore.session.Session'),
+
+    # gql: ignore private classes
+    ('py:class', 'gql.transport.httpx._HTTPXTransport'),
+    ('py:class', 'gql.client._CallableT'),
+]

gql/dsl.py

@@ -347,7 +347,7 @@ def select(
         :type \**fields_with_alias: DSLSelectable
 
         :raises TypeError: if an argument is not an instance of :class:`DSLSelectable`
-        :raises GraphQLError: if an argument is not a valid field
+        :raises graphql.error.GraphQLError: if an argument is not a valid field
         """
         # Concatenate fields without and with alias
         added_fields: Tuple["DSLSelectable", ...] = DSLField.get_aliased_fields(

gql/gql.py

@@ -13,7 +13,7 @@ def gql(request_string: str | Source) -> DocumentNode:
         :class:`async session <gql.client.AsyncClientSession>` or by a
         :class:`sync session <gql.client.SyncClientSession>`
 
-    :raises GraphQLError: if a syntax error is encountered.
+    :raises graphql.error.GraphQLError: if a syntax error is encountered.
     """
     if isinstance(request_string, Source):
         source = request_string

gql/transport/appsync_auth.py

@@ -18,7 +18,7 @@ class AppSyncAuthentication(ABC):
     """AWS authentication abstract base class
 
     All AWS authentication class should have a
-    :meth:`get_headers <gql.transport.appsync.AppSyncAuthentication.get_headers>`
+    :meth:`get_headers <gql.transport.appsync_auth.AppSyncAuthentication.get_headers>`
     method which defines the headers used in the authentication process."""
 
     def get_auth_url(self, url: str) -> str:
@@ -91,7 +91,7 @@ class AppSyncIAMAuthentication(AppSyncAuthentication):
 
     .. note::
         There is no need for you to use this class directly, you could instead
-        intantiate the :class:`gql.transport.appsync.AppSyncWebsocketsTransport`
+        intantiate :class:`gql.transport.appsync_websockets.AppSyncWebsocketsTransport`
         without an auth argument.
 
     During initialization, this class will use botocore to attempt to

gql/transport/requests.py

@@ -54,10 +54,10 @@ def __init__(
         """Initialize the transport with the given request parameters.
 
         :param url: The GraphQL server URL.
-        :param headers: Dictionary of HTTP Headers to send with the :class:`Request`
-            (Default: None).
-        :param cookies: Dict or CookieJar object to send with the :class:`Request`
-            (Default: None).
+        :param headers: Dictionary of HTTP Headers to send with
+            :meth:`requests.Session.request` (Default: None).
+        :param cookies: Dict or CookieJar object to send with
+            :meth:`requests.Session.request` (Default: None).
         :param auth: Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth
             (Default: None).
         :param use_json: Send request body as JSON instead of form-urlencoded