expose livehtml autobuild in Makefile + Add API autodoc (#971)

* expose livehtml autobuild in Makefile

* add API documentation for schema

* document graphene core API

* fixes black lint

* Update graphene/types/union.py

Co-Authored-By: Jonathan Kim <[email protected]>

* Update graphene/types/argument.py

Co-Authored-By: Jonathan Kim <[email protected]>

* Update graphene/types/field.py

Co-Authored-By: Jonathan Kim <[email protected]>

* Update graphene/types/inputfield.py

Co-Authored-By: Jonathan Kim <[email protected]>

* add note about non-functional `interfaces` meta argument in mutation

* update with other virtual environment configuration

* pin autobuild

* format argument example code

* format enum input object and interface examples

* format enum mutation union examples

* revise documentation with imports, capitalization

Author: dvndrsn

.gitignore

@@ -11,6 +11,8 @@ __pycache__/
 # Distribution / packaging
 .Python
 env/
+venv/
+.venv/
 build/
 develop-eggs/
 dist/

Makefile

@@ -3,9 +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:
-	@cd docs &&\
-	pip install -r requirements.txt &&\
-	make html &&\
-	cd -
+docs: install-dev
+	cd docs && make install && make html
+
+.PHONY: docs-live ## Generate docs with live reloading
+docs-live: install-dev
+	cd docs && make install && make livehtml

docs/Makefile

@@ -19,7 +19,11 @@ 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: clean
+.PHONY: install ## to install all documentation related requirements
+install:
+	pip install -r requirements.txt
+
+.PHONY: clean ## to remove all built documentation
 clean:
 	rm -rf $(BUILDDIR)/*
 
@@ -199,6 +203,6 @@ dummy:
 	@echo
 	@echo "Build finished. Dummy builder generates no files."
 
-.PHONY: livehtml
+.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/_static/.gitkeep

@@ -0,0 +1,106 @@
+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
+
+.. autoclass:: graphene.Mutation
+    :members:
+
+Fields (Mounted Types)
+----------------------
+
+.. autoclass:: graphene.Field
+
+.. autoclass:: graphene.Argument
+
+.. autoclass:: graphene.InputField
+
+Fields (Unmounted Types)
+------------------------
+
+.. autoclass:: graphene.types.unmountedtype.UnmountedType
+
+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()
+
+Enum
+----
+
+.. autoclass:: graphene.Enum()
+
+Structures
+----------
+
+.. autoclass:: graphene.List
+
+.. autoclass:: graphene.NonNull
+
+Type Extension
+--------------
+
+.. autoclass:: graphene.Interface()
+
+.. autoclass:: graphene.Union()
+
+Execution Metadata
+------------------
+
+.. autoclass:: graphene.ResolveInfo
+
+.. autoclass:: graphene.Context
+
+.. autoclass:: graphql.execution.base.ExecutionResult
+
+.. Relay
+.. -----
+
+.. .. autoclass:: graphene.Node
+
+.. .. autoclass:: graphene.GlobalID
+
+.. .. autoclass:: graphene.ClientIDMutation
+
+.. .. autoclass:: graphene.Connection
+
+.. .. autoclass:: graphene.ConnectionField
+
+.. .. autoclass:: graphene.PageInfo

docs/api/index.rst

@@ -22,9 +22,10 @@
 # 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 +42,7 @@
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
 ]
 if not on_rtd:
     extensions += ["sphinx.ext.githubpages"]

docs/conf.py

@@ -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/>`_)

docs/index.rst

@@ -1,4 +1,5 @@
 # Required library
 Sphinx==1.5.3
+sphinx-autobuild==0.7.1
 # Docs template
 http://graphene-python.org/sphinx_graphene_theme.zip

docs/requirements.txt

@@ -8,6 +8,37 @@
 
 
 class Argument(MountedType):
+    """
+    Makes an Argument available on a Field in the GraphQL schema.
+
+    Arguments will be parsed and provided to resolver methods for fields as keyword arguments.
+
+    All ``arg`` and ``**extra_args`` for a ``graphene.Field`` are implicitly mounted as Argument
+    using the below parameters.
+
+    .. code:: python
+
+        from graphene import String, Boolean, Argument
+
+        age = String(
+            # Boolean implicitly mounted as Argument
+            dog_years=Boolean(description="convert to dog years"),
+            # Boolean explicitly mounted as Argument
+            decades=Argument(Boolean, default_value=False),
+        )
+
+    args:
+        type (class for a graphene.UnmountedType): must be a class (not an instance) of an
+            unmounted graphene type (ex. scalar or object) which is used for the type of this
+            argument in the GraphQL schema.
+        required (bool): indicates this argument as not null in the graphql scehma. Same behavior
+            as graphene.NonNull. Default False.
+        name (str): the name of the GraphQL argument. Defaults to parameter name.
+        description (str): the description of the GraphQL argument in the schema.
+        default_value (Any): The value to be provided if the user does not set this argument in
+            the operation.
+    """
+
     def __init__(
         self,
         type,

graphene/types/argument.py

@@ -1,4 +1,25 @@
 class Context(object):
+    """
+    Context can be used to make a convenient container for attributes to provide
+    for execution for resolvers of a GraphQL operation like a query.
+
+    .. code:: python
+
+        from graphene import Context
+
+        context = Context(loaders=build_dataloaders(), request=my_web_request)
+        schema.execute('{ hello(name: "world") }', context=context)
+
+        def resolve_hello(parent, info, name):
+            info.context.request  # value set in Context
+            info.context.loaders  # value set in Context
+            # ...
+
+    args:
+        **params (Dict[str, Any]): values to make available on Context instance as attributes.
+
+    """
+
     def __init__(self, **params):
         for key, value in params.items():
             setattr(self, key, value)