From 483053febe2851e179dbd9641999658788786fa7 Mon Sep 17 00:00:00 2001 From: Hanusz Leszek Date: Thu, 12 Dec 2024 11:58:10 +0100 Subject: [PATCH] chore Fix docs sphinx nitpick warnings - adding intersphinx_mapping (#515) --- docs/Makefile | 2 +- docs/code_examples/fastapi_async.py | 1 + docs/conf.py | 50 +++++++++++++++++++++++++++++ gql/dsl.py | 2 +- gql/gql.py | 2 +- gql/transport/appsync_auth.py | 4 +-- gql/transport/requests.py | 8 ++--- 7 files changed, 60 insertions(+), 9 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index d4bb2cbb..747126b3 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/code_examples/fastapi_async.py b/docs/code_examples/fastapi_async.py index 80920252..3bedd187 100644 --- a/docs/code_examples/fastapi_async.py +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index db6e7c5f..94daf942 100644 --- a/docs/conf.py +++ b/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'), +] diff --git a/gql/dsl.py b/gql/dsl.py index 536a8b8b..be2b5a7e 100644 --- a/gql/dsl.py +++ b/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( diff --git a/gql/gql.py b/gql/gql.py index e35c8045..e9705947 100644 --- a/gql/gql.py +++ b/gql/gql.py @@ -13,7 +13,7 @@ def gql(request_string: str | Source) -> DocumentNode: :class:`async session ` or by a :class:`sync session ` - :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 diff --git a/gql/transport/appsync_auth.py b/gql/transport/appsync_auth.py index 5ce93d4e..1eb51b4e 100644 --- a/gql/transport/appsync_auth.py +++ b/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 ` + :meth:`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 diff --git a/gql/transport/requests.py b/gql/transport/requests.py index fd9759ed..bd370908 100644 --- a/gql/transport/requests.py +++ b/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