Revise documentation

[dvndrsn]

• Add missing reference to flask-graphql in integrations
• align documentation for resolver arguments (use root for 1st argument
  instead of self)
• explore use of parent instead of root for first argument
• clarify resolvers and object type documentation
• add documentation for Meta class options for ObjectType
• expand quickstart documentation for first time users
• streamline order of documentation for first time users (broad ->
  specific)
• document resolver quirks

[dvndrsn]

Tried to optimize for first time user experience by explaining some basic GraphQL concepts and putting more explicit linking between relevant parts of the documentation and the open source documentation. Documented some undocumented features for ObjectType Meta class.

There could be more work to be done to keep a light introduction to Graphene concepts that goes from Broad, High level concepts (ex. Schema) to more specific (ObjectType, then Fields). If we had an API reference then we could focus on making a really streamlined first time user experience and then document edge cases and specific API's in the API reference instead of the main body of documentation.

[dvndrsn]

Resolver arguments are inconsistent in documentation - sometimes indicated as self and other times as root - however, there may be a better term to use for the first argument of a resolver.

I did some research in other libraries and documentation and found a couple of different terms that are used. I've listed them in an order that ranks them in how descriptive and accurate they are to describe this first resolver argument.

• parent - this is used in the documentation for apollo server, pretty clear that the value is coming from the parent resolver's result.
• root (or other descriptive argument name) - this is used in blog posts and in the graphql-js core examples, but I think there might be a misunderstanding - graphql-js example code only used root as the first argument name when the resolver is executed in a Root Query or Root Mutation. In other cases, the first argument of the the resolver is named to describe the value object that is being passed into the parameter (ex. character, planet, etc.). This is a good self-documenting approach in code, but may be confusing for documentation.
• subject - this is used in the type implementation for graphql-js core, but a little abstract.
• obj - used in graphql documentation for various libraries (including the other major Python GraphQL libraries), but is a little vague and an abbreviation (not ideal IMO).

In any event, self should probably not be used to describe this argument as resolvers never receive an instance of the class as the first argument of the resolver method. Especially in dynamic languages, naming for parameters is important as we often don't have type systems to tell us what the variable might be. Not naming the first parameter self not agree with linter rules sometimes, but using a different term is most appropriate here.

Let's try to align on one term to use across the documentation.

[jkimbo]

This is fantastic @dvndrsn ! Thank you so much! I've added some comments but let's get this merged in as soon as possible.

Regarding the naming for the "parent" argument for resolvers: my 2 cents is that it should be named after the object it's expecting to get (so person in the case of the Person type). I've written up more about it here: #921 (comment)

[jkimbo]

ResolverParent? Since that is what you are calling it later. Also drop the Argument (or replace with Parameter) because the term arguments is also used to refer to the "arguments" to a field in the schema.

[jkimbo]

👏 👏 👏

[dvndrsn]

@jkimbo, incorporated your suggestions.

@phalt @changeling - any feedback?

[jkimbo]

👍