From 71b4de936997714bca3c79937cf867af78ae7af3 Mon Sep 17 00:00:00 2001 From: Kalle Jepsen Date: Fri, 7 Oct 2016 10:56:01 +0200 Subject: [PATCH] Fixed typos and improved language and markup --- docs/quickstart.rst | 4 ++-- docs/types/abstracttypes.rst | 8 ++++---- docs/types/enums.rst | 12 +++++------- docs/types/interfaces.rst | 15 +++++++-------- docs/types/objecttypes.rst | 29 +++++++++++++---------------- docs/types/scalars.rst | 10 +++++----- docs/types/schema.rst | 29 ++++++++++++++--------------- 7 files changed, 50 insertions(+), 57 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 5a93ff30..90382fcb 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -24,7 +24,7 @@ server with an associated set of resolve methods that know how to fetch data. We are going to create a very simple schema, with a ``Query`` with only -one field: ``hello``. And when we query it should return ``"World"``. +one field: ``hello``. And when we query it, it should return ``"World"``. .. code:: python @@ -41,7 +41,7 @@ one field: ``hello``. And when we query it should return ``"World"``. Querying -------- -Then, we can start querying our schema: +Then we can start querying our schema: .. code:: python diff --git a/docs/types/abstracttypes.rst b/docs/types/abstracttypes.rst index 5e85a804..093cfd93 100644 --- a/docs/types/abstracttypes.rst +++ b/docs/types/abstracttypes.rst @@ -1,21 +1,21 @@ AbstractTypes ============= -An AbstractType contains fields that could be shared among +An AbstractType contains fields that can be shared among ``graphene.ObjectType``, ``graphene.Interface``, ``graphene.InputObjectType`` or other ``graphene.AbstractType``. The basics: - Each AbstractType is a Python class that inherits from ``graphene.AbstractType``. -- Each attribute of the AbstractType represents a field (could be a ``graphene.Field`` or - ``graphene.InputField`` depending on where is mounted) +- Each attribute of the AbstractType represents a field (a ``graphene.Field`` or + ``graphene.InputField`` depending on where it is mounted) Quick example ------------- In this example UserFields is an ``AbstractType`` with a name. ``User`` and -``UserInput`` are two types that will have their own fields +``UserInput`` are two types that have their own fields plus the ones defined in ``UserFields``. .. code:: python diff --git a/docs/types/enums.rst b/docs/types/enums.rst index 85a71686..f0fefd11 100644 --- a/docs/types/enums.rst +++ b/docs/types/enums.rst @@ -47,7 +47,7 @@ needs to have the ``description`` property on it. Usage with Python Enums ----------------------- -In case that the Enums are already defined it's possible to reuse them using +In case the Enums are already defined it's possible to reuse them using the ``Enum.from_enum`` function. .. code:: python @@ -58,10 +58,8 @@ the ``Enum.from_enum`` function. Notes ----- -Internally, ``graphene.Enum`` uses `enum.Enum`_ Python -implementation if available, or a backport if not. +``graphene.Enum`` uses |enum.Enum|_ internally (or a backport if +that's not available) and can be used in the exact same way. -So you can use it in the same way as you would do with Python -``enum.Enum``. - -.. _``enum.Enum``: https://docs.python.org/3/library/enum.html +.. |enum.Enum| replace:: ``enum.Enum`` +.. _enum.Enum: https://docs.python.org/3/library/enum.html diff --git a/docs/types/interfaces.rst b/docs/types/interfaces.rst index ee0410a7..25eefefe 100644 --- a/docs/types/interfaces.rst +++ b/docs/types/interfaces.rst @@ -1,7 +1,7 @@ Interfaces ========== -An Interface contains the essential fields that will be implemented among +An Interface contains the essential fields that will be implemented by multiple ObjectTypes. The basics: @@ -12,8 +12,8 @@ The basics: Quick example ------------- -This example model defines a Character, which has a name. ``Human`` and -``Droid`` are two of the Interface implementations. +This example model defines a ``Character`` interface with a name. ``Human`` +and ``Droid`` are two implementations of that interface. .. code:: python @@ -37,12 +37,11 @@ This example model defines a Character, which has a name. ``Human`` and function = graphene.String() -**name** is a field in the ``Character`` interface that will be in both -``Human`` and ``Droid`` ObjectTypes (as those implement the ``Character`` -interface). Each ObjectType also define extra fields at the same -time. +``name`` is a field on the ``Character`` interface that will also exist on both +the ``Human`` and ``Droid`` ObjectTypes (as those implement the ``Character`` +interface). Each ObjectType may define additional fields. -The above types would have the following representation in a schema: +The above types have the following representation in a schema: .. code:: diff --git a/docs/types/objecttypes.rst b/docs/types/objecttypes.rst index 4006c61a..1c05834d 100644 --- a/docs/types/objecttypes.rst +++ b/docs/types/objecttypes.rst @@ -7,15 +7,14 @@ querying. The basics: -- Each ObjectType is a Python class that inherits +- Each ObjectType is a Python class that inherits from ``graphene.ObjectType``. - Each attribute of the ObjectType represents a ``Field``. Quick example ------------- -This example model defines a Person, which has a first\_name and -last\_name: +This example model defines a Person, with a first and a last name: .. code:: python @@ -33,8 +32,7 @@ last\_name: field is specified as a class attribute, and each attribute maps to a Field. -The above ``Person`` ObjectType would have the following representation -in a schema: +The above ``Person`` ObjectType has the following schema representation: .. code:: @@ -48,16 +46,15 @@ in a schema: Resolvers --------- -A resolver is a method that resolves certain field within a -``ObjectType``. The resolver of a field will be, if not specified -otherwise, the ``resolve_{field_name}`` within the ``ObjectType``. +A resolver is a method that resolves certain fields within a +``ObjectType``. If not specififed otherwise, the resolver of a +field is the ``resolve_{field_name}`` method on the ``ObjectType``. -By default a resolver will take the ``args``, ``context`` and ``info`` -arguments. +By default resolvers take the arguments ``args``, ``context`` and ``info``. -NOTE: The class resolvers in a ``ObjectType`` are treated as ``staticmethod``s -always, so the first argument in the resolver: ``self`` (or ``root``) doesn't -need to be an actual instance of the ``ObjectType``. +NOTE: The resolvers on a ``ObjectType`` are always treated as ``staticmethod``s, +so the first argument to the resolver method ``self`` (or ``root``) need +not be an actual instance of the ``ObjectType``. Quick example @@ -81,7 +78,7 @@ method in the class. Resolvers outside the class ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A field could also specify a custom resolver outside the class: +A field can use a custom resolver from outside the class: .. code:: python @@ -98,8 +95,8 @@ A field could also specify a custom resolver outside the class: Instances as data containers ---------------------------- -Graphene ``ObjectType``\ s could act as containers too. So with the -previous example you could do. +Graphene ``ObjectType``\ s can act as containers too. So with the +previous example you could do: .. code:: python diff --git a/docs/types/scalars.rst b/docs/types/scalars.rst index d8e22b54..382d9f20 100644 --- a/docs/types/scalars.rst +++ b/docs/types/scalars.rst @@ -1,7 +1,7 @@ Scalars ======= -Graphene define the following base Scalar Types: +Graphene defines the following base Scalar Types: - ``graphene.String`` - ``graphene.Int`` @@ -18,7 +18,7 @@ Graphene also provides custom scalars for Dates and JSON: Custom scalars -------------- -You can create a custom scalar for your schema. +You can create custom scalars for your schema. The following is an example for creating a DateTime scalar: .. code:: python @@ -47,8 +47,8 @@ The following is an example for creating a DateTime scalar: Mounting Scalars ---------------- -This scalars if are mounted in a ``ObjectType``, ``Interface`` or -``Mutation``, would act as ``Field``\ s. +Scalars mounted in a ``ObjectType``, ``Interface`` or ``Mutation`` act as +``Field``\ s. .. code:: python @@ -60,7 +60,7 @@ This scalars if are mounted in a ``ObjectType``, ``Interface`` or name = graphene.Field(graphene.String()) -If the types are mounted in a ``Field``, would act as ``Argument``\ s. +Types mounted in a ``Field`` act as ``Argument``\ s. .. code:: python diff --git a/docs/types/schema.rst b/docs/types/schema.rst index 7c7ad73d..3832b6f9 100644 --- a/docs/types/schema.rst +++ b/docs/types/schema.rst @@ -5,6 +5,7 @@ A Schema is created by supplying the root types of each type of operation, query A schema definition is then supplied to the validator and executor. .. code:: python + my_schema = Schema( query=MyRootQuery, mutation=MyRootMutation, @@ -13,11 +14,11 @@ A schema definition is then supplied to the validator and executor. Types ----- -There are some cases where the schema could not access all the types that we plan to have. -For example, when a field returns an ``Interface``, the schema doesn't know any of the +There are some cases where the schema cannot access all of the types that we plan to have. +For example, when a field returns an ``Interface``, the schema doesn't know about any of the implementations. -In this case, we would need to use the ``types`` argument when creating the Schema. +In this case, we need to use the ``types`` argument when creating the Schema. .. code:: python @@ -31,22 +32,22 @@ In this case, we would need to use the ``types`` argument when creating the Sche Querying -------- -If you need to query a schema, you can directly call the ``execute`` method on it. +To query a schema, call the ``execute`` method on it. .. code:: python - + my_schema.execute('{ lastName }') Auto CamelCase field names -------------------------- -By default all field and argument names (that are not +By default all field and argument names (that are not explicitly set with the ``name`` arg) will be converted from -`snake_case` to `camelCase` (`as the API is usually being consumed by a js/mobile client`) +``snake_case`` to ``camelCase`` (as the API is usually being consumed by a js/mobile client) -So, for example if we have the following ObjectType +For example with the ObjectType .. code:: python @@ -54,13 +55,12 @@ So, for example if we have the following ObjectType last_name = graphene.String() other_name = graphene.String(name='_other_Name') -Then the ``last_name`` field name is converted to ``lastName``. +the ``last_name`` field name is converted to ``lastName``. -In the case we don't want to apply any transformation, we can specify -the field name with the ``name`` argument. So ``other_name`` field name -would be converted to ``_other_Name`` (without any other transformation). +In case you don't want to apply this transformation, provide a ``name`` argument to the field constructor. +``other_name`` converts to ``_other_Name`` (without further transformations). -So, you would need to query with: +Your query should look like .. code:: @@ -70,8 +70,7 @@ So, you would need to query with: } -If you want to disable this behavior, you set use the ``auto_camelcase`` argument -to ``False`` when you create the Schema. +To disable this behavior, set the ``auto_camelcase`` to ``False`` upon schema instantiation. .. code:: python