From 79f84706ec55bd53b83156a055922242b9ad4496 Mon Sep 17 00:00:00 2001 From: Dave A Date: Sat, 25 May 2019 05:38:06 -0400 Subject: [PATCH] add API documentation for schema --- Makefile | 11 ++++- docs/Makefile | 2 +- docs/_static/.gitkeep | 0 docs/api/index.rst | 101 +++++++++++++++++++++++++++++++++++++++ docs/conf.py | 7 +-- docs/index.rst | 3 +- graphene/types/schema.py | 48 +++++++++++++++++-- 7 files changed, 162 insertions(+), 10 deletions(-) create mode 100644 docs/_static/.gitkeep create mode 100644 docs/api/index.rst diff --git a/Makefile b/Makefile index a905f831..b4e6c928 100644 --- a/Makefile +++ b/Makefile @@ -3,10 +3,17 @@ help: @echo "Please use \`make ' where is one of" @grep -E '^\.PHONY: [a-zA-Z_-]+ .*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = "(: |##)"}; {printf "\033[36m%-30s\033[0m %s\n", $$2, $$3}' +.PHONY: install-dev ## Install development dependencies +install-dev: + pip install -e ".[test]" + +test: + py.test graphene + .PHONY: docs ## Generate docs -docs: +docs: install-dev cd docs && make install && make html .PHONY: docs-live ## Generate docs with live reloading -docs-live: +docs-live: install-dev cd docs && make install && make livehtml diff --git a/docs/Makefile b/docs/Makefile index fbc76577..8753f299 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -205,4 +205,4 @@ dummy: .PHONY: livehtml ## to build and serve live-reloading documentation livehtml: - sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + sphinx-autobuild -b html --watch ../graphene $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 00000000..86460918 --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,101 @@ +API Reference +============= + +Schema +------ + +.. autoclass:: graphene.types.schema.Schema + :members: + +.. Uncomment sections / types as API documentation is fleshed out +.. in each class + +.. Object types +.. ------------ + +.. .. autoclass:: graphene.ObjectType + +.. .. autoclass:: graphene.InputObjectType + +.. Fields (Mounted Types) +.. ---------------------- + +.. .. autoclass:: graphene.Field + +.. .. autoclass:: graphene.Argument + +.. .. autoclass:: graphene.InputField + +.. GraphQL Scalars +.. --------------- + +.. .. autoclass:: graphene.Int + +.. .. autoclass:: graphene.Float + +.. .. autoclass:: graphene.String + +.. .. autoclass:: graphene.Boolean + +.. .. autoclass:: graphene.ID + +.. Graphene Scalars +.. ---------------- + +.. .. autoclass:: graphene.Date + +.. .. autoclass:: graphene.DateTime + +.. .. autoclass:: graphene.Time + +.. .. autoclass:: graphene.Decimal + +.. .. autoclass:: graphene.UUID + +.. .. autoclass:: graphene.JSONString + +.. Structures +.. ---------- + +.. .. autoclass:: graphene.List + +.. .. autoclass:: graphene.NonNull + +.. Enum +.. ---- + +.. .. autoclass:: graphene.Enum + +.. Type Extension +.. -------------- + +.. .. autoclass:: graphene.Interface + +.. .. autoclass:: graphene.Union + +.. Execution Metadata +.. ------------------ + +.. .. autoclass:: graphene.ResolveInfo + +.. .. autoclass:: graphene.Context + +.. Mutation +.. -------- + +.. .. autoclass:: graphene.Mutation + +.. Relay +.. ----- + +.. .. autoclass:: graphene.Node + +.. .. autoclass:: graphene.GlobalID + +.. .. autoclass:: graphene.ClientIDMutation + +.. .. autoclass:: graphene.Connection + +.. .. autoclass:: graphene.ConnectionField + +.. .. autoclass:: graphene.PageInfo diff --git a/docs/conf.py b/docs/conf.py index c7927ec2..b67e3a21 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,9 +22,9 @@ on_rtd = os.environ.get("READTHEDOCS", None) == "True" # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import os +import sys +sys.path.insert(0, os.path.abspath('..')) # -- General configuration ------------------------------------------------ @@ -41,6 +41,7 @@ extensions = [ "sphinx.ext.todo", "sphinx.ext.coverage", "sphinx.ext.viewcode", + "sphinx.ext.napoleon", ] if not on_rtd: extensions += ["sphinx.ext.githubpages"] diff --git a/docs/index.rst b/docs/index.rst index aff3960f..eb78f902 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,9 +11,10 @@ Contents: execution/index relay/index testing/index + api/index Integrations ------ +------------ * `Graphene-Django `_ (`source `_) * `Graphene-SQLAlchemy `_ (`source `_) diff --git a/graphene/types/schema.py b/graphene/types/schema.py index a885c88a..07c25763 100644 --- a/graphene/types/schema.py +++ b/graphene/types/schema.py @@ -27,10 +27,26 @@ def assert_valid_root_type(_type): class Schema(GraphQLSchema): """ - Schema Definition + Graphene Schema can execute operations (query, mutation, subscription) against the defined + types. - A Schema is created by supplying the root types of each type of operation, - query and mutation (optional). + For advanced purposes, the schema can be used to lookup type definitions and answer questions + about the types through introspection. + + Args: + query (ObjectType): Root query *ObjectType*. Describes entry point for fields to *read* + data in your Schema. + mutation (ObjectType, optional): Root mutation *ObjectType*. Describes entry point for + fields to *create, update or delete* data in your API. + subscription (ObjectType, optional): Root subscription *ObjectType*. Describes entry point + for fields to receive continuous updates. + directives (List[GraphQLDirective], optional): List of custom directives to include in + GraphQL schema. Defaults to only include directives definved by GraphQL spec (@include + and @skip) [GraphQLIncludeDirective, GraphQLSkipDirective]. + types (List[GraphQLType], optional): List of any types to include in schema that + may not be introspected through root types. + auto_camelcase (bool): Fieldnames will be transformed in Schema's TypeMap from snake_case + to camelCase (preferred by GraphQL standard). Default True. """ def __init__( @@ -99,6 +115,32 @@ class Schema(GraphQLSchema): raise Exception("{} is not a valid GraphQL type.".format(_type)) def execute(self, *args, **kwargs): + """ + Use the `graphql` function from `graphql-core` to provide the result for a query string. + Most of the time this method will be called by one of the Graphene :ref:`Integrations` + via a web request. + + Args: + request_string (str or Document): GraphQL request (query, mutation or subscription) in + string or parsed AST form from `graphql-core`. + root (Any, optional): Value to use as the parent value object when resolving root + types. + context (Any, optional): Value to be made avaiable to all resolvers via + `info.context`. Can be used to share authorization, dataloaders or other + information needed to resolve an operation. + variables (dict, optional): If variables are used in the request string, they can be + provided in dictionary form mapping the variable name to the variable value. + operation_name (str, optional): If mutiple operations are provided in the + request_string, an operation name must be provided for the result to be provided. + middleware (List[SupportsGraphQLMiddleware]): Supply request level middleware as + defined in `graphql-core`. + backend (GraphQLCoreBackend, optional): Override the default GraphQLCoreBackend. + **execute_options (Any): Depends on backend selected. Default backend has several + options such as: validate, allow_subscriptions, return_promise, executor. + + Returns: + :obj:`ExecutionResult` containing any data and errors for the operation. + """ return graphql(self, *args, **kwargs) def introspect(self):