fix typos, wording, punctuation, other errors in docs (#668)

docs/graphql/manual/api-reference/index.rst

@@ -35,7 +35,7 @@ The following lists all the types of requests that can be made using the Schema/
 
 Supported PostgreSQL types
 --------------------------
-You can refer the following to know about all PostgreSQL types supported by the Hasura GraphQL engine:
+You can refer to the following to know about all PostgreSQL types supported by the Hasura GraphQL engine:
 
 - :doc:`Supported PostgreSQL types <postgresql-types>`
 

docs/graphql/manual/api-reference/postgresql-types.rst

@@ -119,7 +119,7 @@ E.g.
 
 Date
 ----
-GraphQL custom scalar with name **date**. Date (no time of day). Allowed values are yyyy-mm-dd
+GraphQL custom scalar with name **date**. Date (no time of day). Allowed values are yyyy-mm-dd.
 
 E.g.
 
@@ -136,8 +136,8 @@ E.g.
 
 Time with time zone
 -------------------
-Graphql custom scalar type with name **timetz**. Time of day only, with time zone. Allowed values should be of ISO8601 format.
-Eg. 17:30:15Z, 17:30:15+05:30, 17:30:15.234890+05:30
+GraphQL custom scalar type with name **timetz**. Time of day only, with time zone. Allowed values should be of ISO8601 format
+(e.g. 17:30:15Z, 17:30:15+05:30, 17:30:15.234890+05:30).
 
 E.g.
 
@@ -154,8 +154,8 @@ E.g.
 
 Timestamp with time zone
 ------------------------
-Graphql custom scalar type with name **timestamptz**. Both date and time, with time zone. Allowed values should be of ISO8601 format.
-Eg. 2016-07-20T17:30:15Z, 2016-07-20T17:30:15+05:30, 2016-07-20T17:30:15.234890+05:30
+GraphQL custom scalar type with name **timestamptz**. Both date and time, with time zone. Allowed values should be of ISO8601 format
+(e.g. 2016-07-20T17:30:15Z, 2016-07-20T17:30:15+05:30, 2016-07-20T17:30:15.234890+05:30).
 
 E.g.
 
@@ -212,7 +212,7 @@ E.g.
      }
    }
 
-variable:-
+variable:
 
 .. code-block:: json
 

docs/graphql/manual/auth/basics.rst

@@ -2,13 +2,12 @@ Access control basics
 =====================
 
 In this section, we're going to setup a simple access control rule for restricting querying on a table.
-We're working with a simple author table where users have some information stored about themselves in the
-``author`` table.
+We're working with a simple ``author`` table where users have some information stored about themselves.
 
 Create a author table
 ---------------------
 
-Head to your console and create the ``author`` table the following columns:
+Head to your console and create a ``author`` table with the following columns:
 
 +----------+--------+
 |      id  | integer|
@@ -80,12 +79,12 @@ Let's add a **select** permission for the **user** role on the ``author`` table:
             }
           }
 
-Now, let's make the same query as above but include the 2 dynamic authorization variables via request headers.
-``X-Hasura-Role`` and ``X-Hasura-User-Id`` which will automatically get used according to the permission rule we set up.
+Now, let's make the same query as above but also include 2 dynamic authorization variables via request headers.
+``X-Hasura-Role`` and ``X-Hasura-User-Id`` will automatically get used according to the permission rule we set up.
 
 .. image:: ../../../img/graphql/manual/auth/query-with-perms.png
 
-You can notice above, how the same query now only includes the right slice of data.
+You can notice above how the same query now only includes the right slice of data.
 
 .. _restrict_columns:
 

docs/graphql/manual/auth/index.rst

@@ -1,8 +1,8 @@
 Authentication / Access control
 ===============================
 
-Hasura helps you define granular access controls for every field in your GraphQL schema, basically every table or
-view in your Postgres schema. These access control rules can use dynamic variables that come in with every request.
+Hasura helps you define granular access controls for every field in your GraphQL schema (i.e. every table or
+view in your Postgres schema). These access control rules can use dynamic variables that come in with every request.
 
 .. image:: ../../../img/graphql/manual/auth/hasura-perms.png
 
@@ -16,7 +16,7 @@ directly!
 Your app will likely only send an authorization token or cookie provided by your app's authentication
 system to Hasura. In this case, Hasura will make a request to a webhook set up by you with the request headers your
 app has sent (authorization tokens, cookies etc). The webhook should then return the variables required as context for
-the access control rules. Alternatively, your app can send JWT tokens to Hasura which can be then decoded by Hasura to
+the access control rules. Alternatively, your app can send to Hasura JWT tokens, which can then be decoded by Hasura to
 get the variables required for the access control rules.
 See :doc:`webhook` or :doc:`jwt` for more details.
 

docs/graphql/manual/auth/roles-variables.rst

@@ -7,7 +7,7 @@ use-cases conveniently.
 Roles
 -----
 Every table/view can have permission rules that are grouped together by multiple roles.
-By default, there is an ``admin`` role that can perform any operation or any table.
+By default, there is an ``admin`` role that can perform any operation on any table.
 
 You can create your own roles that make it easy for you to group permissions together.
 
@@ -39,7 +39,7 @@ When you create a permission, or an access control rule, the permission rule its
 that are derived from the request itself. Let's refer to these as *session variables*.
 
 For example: If a user makes a request, the session token maps to a ``user-id``. This ``user-id`` can be used in
-a permission to represent that inserts into a table are only allowed if the ``user_id`` column has a value equal to that
+a permission to show that inserts into a table are only allowed if the ``user_id`` column has a value equal to that
 of ``user-id``, the session variable.
 
 When you are constructing permission rules, however, there might be several variables that represent the business logic
@@ -88,7 +88,7 @@ Examples:
 Indicating roles and session-variables in a GraphQL request
 -----------------------------------------------------------
 
-Now that we have these roles and permission rules that use session-variables set up, how do we actually use them
+Now that we have these roles and permission rules that use session variables set up, how do we actually use them
 when we make GraphQL requests from an app or from a different service?
 
 Option 1: Development & Testing
@@ -115,7 +115,7 @@ session token (authorization token, JWT, cookie etc.) that your app normally use
 
 Read more about :doc:`configuring webhook authentication for Hasura<webhook>`.
 
-There are 4 different types of operations for which you can define permissions on a table, ie: Select, Insert,
+There are 4 different types of operations for which you can define permissions on a table: Select, Insert,
 Update and Delete.
 
 

docs/graphql/manual/auth/webhook.rst

@@ -2,7 +2,7 @@ Authorization using webhooks
 ============================
 
 You can configure a webhook (see :doc:`GraphQL server options <../deployment/graphql-engine-flags/reference>`) to
-authenticate all incoming requests to Hasura GraphQL engine server.
+authenticate all incoming requests to the Hasura GraphQL engine server.
 
 .. image:: ../../../img/graphql/manual/auth/webhook-auth.png
 
@@ -20,7 +20,7 @@ Spec for the webhook
 
 Request
 ^^^^^^^
-Hasura will send ``GET`` request to you webhook with **all headers it received from client**
+Hasura will send a ``GET`` request to your webhook with **all headers it received from client:**
 
 .. code-block:: http
 
@@ -33,7 +33,7 @@ Response
 Success
 +++++++
 To allow the GraphQL request to go through, your webhook must return a ``200`` status code.
-You should send the ``X-Hasura-*`` "session variables" your permission rules in Hasura.
+You should send the ``X-Hasura-*`` "session variables" to your permission rules in Hasura.
 
 .. code-block:: http
 
@@ -48,7 +48,7 @@ You should send the ``X-Hasura-*`` "session variables" your permission rules in
    }
 
 .. note::
-   All values should be ``String``, they will be converted to the right type automatically.
+   All values should be ``String``. They will be converted to the right type automatically.
 
 Failure
 +++++++
@@ -59,8 +59,8 @@ If you want to deny the GraphQL request return a ``401 Unauthorized`` exception.
    HTTP/1.1 401 Unauthorized
 
 .. note::
-   Anything other than ``200`` or ``401`` response from webhook then server raises ``500 Internal Server Error``
-   exception
+   Anything other than a ``200`` or ``401`` response from webhook makes server raise a ``500 Internal Server Error``
+   exception.
 
 See:
 ----

docs/graphql/manual/migrations/existing-project.rst

@@ -7,8 +7,8 @@ to start using migrations to help you track the database and GraphQL schema chan
 These are the steps you need to follow:
 
 #. Install the Hasura CLI
-#. Setup a project dir
-#. Initialise migrations
+#. Setup a project directory
+#. Initialize migrations
 #. For further changes, use the Hasura CLI console (``http://localhost:9695``) instead of the console served by the
    GraphQL engine (Eg: ``http://my-graphql.herokuapp.com``)
 
@@ -70,30 +70,30 @@ Skip this step if you already have a project directory.
 
   hasura init --directory my-project --endpoint http://my-graphql.herokuapp.com
 
-Step 3: Initialise the migrations as per your current state
+Step 3: Initialize the migrations as per your current state
 -----------------------------------------------------------
 
-- Install ``pg_dump`` (or use docker) and run the following command to download the public schema as ``public-schema.sql``:
+- Install ``pg_dump`` (or use Docker) and run the following command to download the public schema as ``public-schema.sql``:
 
   .. code-block:: bash
   
      pg_dump -O -x -h <db-host> -p <db-port> -U <db-user> -d <db-name> --schema public --schema-only > public-schema.sql
 
-- Export the metadata (this creates a file ``metadata.yaml``)
+- Export the metadata (this creates a file ``metadata.yaml``):
 
   .. code-block:: bash
      
      hasura metadata export
 
-- Create a new migration with a name, say ``first``. This will generate some files in ``migrations/`` directory
+- Create a new migration with a name, say ``first``. This will generate some files in ``migrations/`` directory:
 
   .. code-block:: bash
   
      hasura migrate create first
 
 - Move the contents of ``public-schema.sql`` to ``migrations/<version>_first.up.sql``
-- Move the contents of ``metadata.yaml`` to ``migrations/<version>_first.up.yaml`` with the following content:
-  (take care of indentation)
+- Move the contents of ``metadata.yaml`` to ``migrations/<version>_first.up.yaml`` with the following content
+  (take care of indentation):
 
   .. code-block:: yaml
 
@@ -101,7 +101,7 @@ Step 3: Initialise the migrations as per your current state
        args:
          <contents-of-metadata.yaml>
 
-- Remove ``migrations/<version>_first.down.{sql,yaml}`` migration files if you are not adding down migrations for these.
+- Remove ``migrations/<version>_first.down.{sql,yaml}`` migration files if you are not adding down migrations for these
 
 Step 4: Use the console from the CLI
 ------------------------------------
@@ -129,7 +129,7 @@ in the ``migrations/`` directory in your project.
 Step 6: Apply the migrations to another instance of the GraphQL engine
 ----------------------------------------------------------------------
 
-- Edit ``config.yaml`` and change the endpoint to another instance, say ``https://my-another-grapqhl.herokuapp.com``
+- Edit ``config.yaml`` and change the endpoint to another instance, say ``https://my-another-grapqhl.herokuapp.com``:
 
   .. code-block:: yaml
 
@@ -147,4 +147,4 @@ Step 7: Create migrations without the console & other advanced actions
 
 - Each migration consists of a pair of yaml and sql files with up and down steps.
 - Create migrations manually using :ref:`migrate create <hasura_migrate_create>`.
-- You can apply only certain versions or number of steps. Read more at :ref:`migrate apply <hasura_migrate_apply>`
+- You can apply only certain versions or numbers of steps. Read more at :ref:`migrate apply <hasura_migrate_apply>`

docs/graphql/manual/migrations/new-project.rst

@@ -2,14 +2,14 @@ Migrations for a new project
 ============================
 
 This guide will help you if you are about to start setting up your schema from scratch. You can use migrations
-to help you track the database and GraphQL schema changes.
+to help track the database and GraphQL schema changes.
 
 These are the steps you need to follow:
 
 #. Install the Hasura CLI
-#. Setup a project dir
+#. Setup a project directory
 #. Use the Hasura CLI console (``http://localhost:9695``) instead of the console served by the
-   GraphQL engine (Eg: ``http://my-graphql.herokuapp.com``) to set the schema up.
+   GraphQL engine (Eg: ``http://my-graphql.herokuapp.com``) to set the schema up
 
 
 Step 0: Take a note of your  GraphQL engine endpoint
@@ -95,7 +95,7 @@ in the ``migrations/`` directory in your project.
 Step 5: Apply the migrations to another instance of the GraphQL engine
 ----------------------------------------------------------------------
 
-- Edit ``config.yaml`` and change the endpoint to another instance, say ``https://my-another-grapqhl.herokuapp.com``
+- Edit ``config.yaml`` and change the endpoint to another instance, say ``https://my-another-grapqhl.herokuapp.com``:
 
   .. code-block:: yaml
 
@@ -113,4 +113,4 @@ Step 6: Create migrations without the console & other advanced actions
 
 - Each migration consists of a pair of yaml and sql files with up and down steps.
 - Create migrations manually using :ref:`migrate create <hasura_migrate_create>`.
-- You can apply only certain versions or number of steps. Read more at :ref:`migrate apply <hasura_migrate_apply>`
+- You can apply only certain versions or numbers of steps. Read more at :ref:`migrate apply <hasura_migrate_apply>`

docs/graphql/manual/mutations/index.rst

@@ -1,6 +1,6 @@
 Mutations
 =========
-GraphQL mutations are used to modify server-side data i.e. write, update or delete data. As with queries, mutation
+GraphQL mutations are used to modify server-side data (i.e. write, update or delete data). As with queries, mutation
 fields are auto-generated based on the Postgres schema. Here’s a sample mutation field from our reference
 author/article schema:
 
@@ -22,7 +22,7 @@ author/article schema:
 As you can see from the schema, you can:
 
 #. Pass multiple objects to the mutation.
-#. Return objects (with nested objects), from the affected rows, in the response.
+#. Return objects (with nested objects) from the affected rows in the response.
 
 Let's use this reference author/article schema to look at different types of mutations.
 

docs/graphql/manual/mutations/multiple-mutations.rst

@@ -1,7 +1,7 @@
 Multiple mutations in a request
 ===============================
 If multiple mutations are part of the same request, they are executed **sequentially**. If any of the mutations fail,
-all the executed mutations will be rolled back. i.e. all the mutations are run as a **transaction**.
+all the executed mutations will be rolled back (i.e. all the mutations are run as a **transaction**).
 
 Example: Insert objects of different types in the same mutation
 ---------------------------------------------------------------

docs/graphql/manual/schema/enums.rst

@@ -8,30 +8,30 @@ to another table which contains the reference list of allowed values. This ensur
 only if it exists in the reference table.
 
 **For example**: let's say we have a table ``magazine`` with fields ``(id, title, issue_month, issue_year)``
-and we would like to restrict the values of the ``issue_month`` field to just the months of the year, ie: January,
-February and so on.
+and we would like to restrict the values of the ``issue_month`` field to just the months of the year (i.e. January,
+February, and so on).
 
 1) Create a reference table for the enum
 ----------------------------------------
 
 Open the Hasura console and head to the ``Data -> Create table`` interface.
 
-Create a table ``months_of_the_year`` with just one column ``month`` which is the primary key:
+Create a table ``months_of_the_year`` with just one column ``month``, which is the primary key:
 
 .. image:: ../../../img/graphql/manual/schema/enum-create-ref-table.png
 
 2) Add the allowed enum values to the reference table
 -----------------------------------------------------
 
-Head to the ``GraphiQL`` tab of the console and run an insert mutation to insert the allowed enum values.
+Head to the ``GraphiQL`` tab of the console and run an insert mutation to insert the allowed enum values:
 
 .. image:: ../../../img/graphql/manual/schema/enum-insert-ref-values.png
 
 3) Set a foreign-key to the reference table
 -------------------------------------------
 
-Head to ``Data -> magazine -> Modify`` tab of the console and set a foreign-key to the ``months_of_the_year`` table
-using the fields: ``issue_month -> months_of_the_year :: month``.
+Head to the ``Data -> magazine -> Modify`` tab of the console and set a foreign-key to the ``months_of_the_year`` table
+using the fields: ``issue_month -> months_of_the_year :: month``:
 
 .. image:: ../../../img/graphql/manual/schema/enum-set-foreign-key.png
 

docs/graphql/manual/schema/export-graphql-schema.rst

@@ -3,12 +3,12 @@ Exporting the Hasura GraphQL schema
 
 If you need to share or export the GraphQL schema, you can use community tooling such as
 `graphqurl <https://github.com/hasura/graphqurl>`_, `apollo <https://github.com/apollographql/apollo-cli>`_,
-`get-graphql-schema <https://github.com/prismagraphql/get-graphql-schema>`_ etc.
+`get-graphql-schema <https://github.com/prismagraphql/get-graphql-schema>`_, etc.
 
 For example, using ``graphqurl``, you can get the schema as follows:
 
 Run ``npm install -g graphqurl`` to install ``graphqurl``. Then you can run the following commands to download the
-GraphQL schema.
+GraphQL schema:
 
 .. code-block:: bash
 
@@ -20,7 +20,7 @@ GraphQL schema.
   gq https://my-graphql-engine.com/v1alpha1/graphql -H 'X-Hasura-Access-Key: secretaccesskey' --introspect > schema.graphql
 
 By default, it downloads the schema in ``.graphql`` format. If you want it in JSON format, you can use an additional
-flag ``--format json``.
+flag ``--format json``:
 
 .. code-block:: bash
 

docs/graphql/manual/schema/how-it-works.rst

@@ -1,10 +1,10 @@
 How Hasura's GraphQL schema generation works
 ============================================
 
-Given your Postgres database, Hasura GraphQL engine can automatically generate a GraphQL schema and process GraphQL
+Given your Postgres database, Hasura GraphQL engine can automatically generate a GraphQL schema and process both GraphQL
 queries and mutations.
 
-How does Hasura GraphQL engine know which tables and views in which schema, and how to connect them so that they
+How does Hasura GraphQL engine know which tables and views are in which schema and how to connect them so that they
 form a graph over which queries and mutations should be allowed?
 
 Here's what Hasura GraphQL engine does under the hood:
@@ -34,11 +34,11 @@ Relationships or Connections
 
 Between one table/view and another table/view you can tell Hasura GraphQL engine to create a relationship or a
 connection between
-these 2 nodes in a graph, using a particular column as a link. Often, you have foreign-key constraints that
+their 2 nodes in a graph, using a particular column as a link. Often, you have foreign-key constraints that
 indicate a relationship and you can tell Hasura GraphQL engine to use that foreign-key constraint to create a
 relationship too.
 
-You can specify an ``object relationship`` or an ``array relationship`` between table and views. For example:
+You can specify an ``object relationship`` or an ``array relationship`` between tables and views. For example:
 
 #. You might have a ``restaurant.average_rating`` where ``average_rating`` is a view connected to the ``restaurant``
    table via a ``restaurant_id``.
@@ -46,15 +46,15 @@ You can specify an ``object relationship`` or an ``array relationship`` between
 
 When you create a relationship, Hasura GraphQL engine does the following:
 
-#. Augments the types of the tables/views involved by adding a reference to the nested type
+#. Augments the types of tables/views involved by adding a reference to the nested type
 #. Augments the possible ``where`` and ``order_by`` clauses that can be used to enable nested filtering and sorting
 
 Resolvers
 ---------
 
-Hasura GraphQL engine does not have any resolvers. The Hasura GraphQL engine is actually a compiler, that compiles
+Hasura GraphQL engine does not have any resolvers. The Hasura GraphQL engine is actually a compiler that compiles
 your GraphQL query into an SQL query.
-Hasura's GraphQL syntax is also optimised to expose the power of the underlying SQL so that you can make powerful
+Hasura's GraphQL syntax is also optimized to expose the power of the underlying SQL so that you can make powerful
 queries via GraphQL.
 
 Metadata

docs/graphql/manual/schema/index.rst

@@ -2,7 +2,7 @@ Schema
 ======
 
 Hasura GraphQL engine automatically generates your GraphQL schema and resolvers based on your tables/views
-in Postgres. **You don't need to write a GraphQL schema, you don't need to write resolvers.**
+in Postgres. **You don't need to write a GraphQL schema or resolvers.**
 
 The Hasura console gives you UI tools that speed up your data-modelling process or working with your existing database.
 The console also automatically generates migrations or metadata files that you can edit directly and check into your

docs/graphql/manual/schema/sql-functions.rst

@@ -5,21 +5,21 @@ Let's say you want to set the value of some fields as the output of some custom
 
 This can be achieved by:
 
-#. Modifying the table to allow the columns we want to be set by the SQL functions as nullable (to allow the initial
+#. Modifying the table to allow the columns we want to be set by the SQL functions to be nullable (to allow the initial
    insert before the SQL function is run).
 #. Creating an insert/update trigger on the table that calls your SQL function and sets the output values in the output
    columns.
 #. Making your mutation requests without setting the SQL function output columns.
 
 **For example**, say we have a table ``sql_function_table`` with columns ``input`` and ``output`` and we would like
-to set the value of the ``output`` column as the uppercased value of the string received in ``input`` field.
+to set the value of the ``output`` column as the uppercased value of the string received in the ``input`` field.
 
 1) Modify the table
 -------------------
 
 Modify the table ``sql_function_table`` and make its ``output`` column nullable.
 
-Open the console and head to ``Data -> sql_function_table -> Modify``
+Open the console and head to ``Data -> sql_function_table -> Modify``:
 
 .. image:: ../../../img/graphql/manual/schema/modify-sql-fn-table.png
 
@@ -27,7 +27,7 @@ Open the console and head to ``Data -> sql_function_table -> Modify``
 -------------------
 
 The below SQL defines a ``trigger`` which will simply uppercase the value passed in the ``input`` field and set it to
-the ``output`` field whenever an insert or update is made to the ``sql_function_table``.
+the ``output`` field whenever an insert or update is made to the ``sql_function_table``:
 
 .. code-block:: plpgsql
 
@@ -82,5 +82,5 @@ value (output="YABBA DABBA DOO!") will be set automatically.
 
 .. note::
 
-  This approach enforces the value set in the field to always be the result of the defined SQL function unlike
-  :doc:`setting a default value <default-values>` instead.
+  This approach enforces the value set in the field to always be the result of the defined SQL function, unlike
+  :doc:`setting a default value <default-values>`.

docs/graphql/manual/schema/using-existing-database.rst

@@ -4,7 +4,7 @@ Setting up schema using an existing database
 When you have an existing database with a schema already present, you don't need to create tables or views or run
 DDL queries through the Hasura console.
 
-All you need to do is indicate to Hasura GraphQL engine, which tables and views you want to expose over GraphQL and
+All you need to do is indicate to Hasura GraphQL engine which tables and views you want to expose over GraphQL and
 how they are connected to each other so that you can query them as a "graph".
 
 1) Track tables/views
@@ -27,8 +27,7 @@ To track all tables and views present in the database:
 2) Track foreign-keys
 ---------------------
 
-Tracking a foreign-key means creating a :doc:`relationship <relationships/index>` between the tables involved in the foreign
-key.
+Tracking a foreign-key means creating a :doc:`relationship <relationships/index>` between the tables involved in the foreign-key.
 
 To track a foreign-key between two tables in the database:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -36,7 +35,7 @@ To track a foreign-key between two tables in the database:
 #. Head to the ``Data -> Schema`` section of the console.
 #. Click on a table involved in the foreign-key and head to the ``Relationships`` tab.
 #. You should see a suggested relationship based on the foreign-key. Click ``Add``, give a name to your relationship
-   (this will be the name of the :doc:`nested object <../queries/nested-object-queries>` in the GraphQL query) and
+   (this will be the name of the :doc:`nested object <../queries/nested-object-queries>` in the GraphQL query), and
    hit ``Save`` to create the relationship.
 #. Repeat with the other table involved in the foreign-key.
 

docs/graphql/manual/schema/views.rst

@@ -3,13 +3,13 @@ Customise schema with views
 
 You may want to customise your GraphQL schema to:
 
-- Limit scope i.e. expose only a subset of the columns in a table
-- Fetch derived data (*aggregations like count, average, etc.*) in queries
+- Limit scope (i.e. expose only a subset of the columns in a table)
+- Fetch derived data (aggregations like *count, average, etc.*) in queries
 
 These use-cases can be supported using database views.
 
 You can create views `using SQL <https://www.postgresql.org/docs/9.6/static/sql-createview.html>`_ which you can
-run using the console at the ``Data -> SQL`` section.
+run using the console in the ``Data -> SQL`` section.
 
 Please see the following pages for details about the above use-cases: