add API documentation for schema

Makefile

@@ -3,10 +3,17 @@ help:
 	@echo "Please use \`make <target>' where <target> 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

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

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

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"]

docs/index.rst

@@ -11,9 +11,10 @@ Contents:
    execution/index
    relay/index
    testing/index
+   api/index
 
 Integrations
------
+------------
 
 * `Graphene-Django <http://docs.graphene-python.org/projects/django/en/latest/>`_ (`source <https://github.com/graphql-python/graphene-django/>`_)
 * `Graphene-SQLAlchemy <http://docs.graphene-python.org/projects/sqlalchemy/en/latest/>`_ (`source <https://github.com/graphql-python/graphene-sqlalchemy/>`_)

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):