misc docs update (#1374)

docs/graphql/manual/auth/basics.rst

@@ -9,18 +9,17 @@ Access control basics
 In this section, we're going to set up 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.
 
-Create an author table
-----------------------
+Create a table
+--------------
 
-Head to your console and create an ``author`` table with the following columns:
+Head to your console and :ref:`create a table <create-tables>` called ``author`` with the following schema:
 
-+----------+--------+
-|      id  | integer|
-+----------+--------+
-| name     | text   |
-+----------+--------+
+.. code-block:: sql
 
-.. image:: ../../../img/graphql/manual/auth/author-table.png
+  author (
+    id INT PRIMARY KEY,
+    name TEXT
+  )
 
 Insert some sample data into the table:
 
@@ -39,6 +38,8 @@ Insert some sample data into the table:
 Try out a query
 ---------------
 
+Head to the ``GraphiQL`` tab in your console and try out the below query:
+
 .. code-block:: graphql
 
   query {
@@ -49,7 +50,7 @@ Try out a query
   }
 
 You'll see that this results in a response that contains all the authors because by default the GraphQL query is
-accepted with admin permissions.
+accepted with **admin** permissions.
 
 .. image:: ../../../img/graphql/manual/auth/fetch-authors.png
 
@@ -59,10 +60,14 @@ Add a simple access control rule for a logged in user
 
 Let's say that for our app, logged in users are only allowed to fetch their own data.
 
+Head to the ``Permissions`` tab of the ``author`` table.
+
 Let's add a **select** permission for the **user** role on the ``author`` table:
 
 .. image:: ../../../img/graphql/manual/auth/author-select-perms.png
 
+This reads as:
+
 .. list-table::
    :header-rows: 1
    :widths: 15 20 25 40
@@ -84,13 +89,27 @@ Let's add a **select** permission for the **user** role on the ``author`` table:
             }
           }
 
-Now, let's make the same query as above but also include two 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.
+Now, let's make the same query as above but also include two dynamic authorization variables ``X-Hasura-Role`` and
+``X-Hasura-User-Id`` via request headers. These 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.
 
+.. admonition:: Permission rules can also use nested object's fields
+
+  For example, for an ``article`` table with nested ``author`` table, we can define the select permission as:
+
+  .. code-block:: json
+
+    {
+      "author" : {
+        "id": {
+          "_eq": "X-Hasura-User-Id"
+        }
+      }
+    }
+
 .. _restrict_columns:
 
 Restrict access to certain columns

docs/graphql/manual/auth/index.rst

@@ -6,24 +6,25 @@ Authentication / Access control
   :depth: 1
   :local:
 
-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.
+Hasura helps you define granular access control rules for every field in your GraphQL schema. These access control
+rules use dynamic session variables that are passed with every request to define both row and column level permissions
+on your data.
+
+**For example:**
 
 .. image:: ../../../img/graphql/manual/auth/hasura-perms.png
+   :width: 80 %
 
-**While developing**, you can send variables as request headers directly.
+**While developing**, you can send the session variables as request headers directly.
 
-.. image:: ../../../img/graphql/manual/auth/dev-mode-auth.png
-
-However, **in production**, when your application is deployed, your app can't send these authorization variables
-directly!
-
-Your app will likely only send an authorization token or cookie provided by your app's authentication
+However, **in production** when your application is deployed, your app can't send these authorization variables
+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 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.
+
+See :doc:`webhook` or :doc:`jwt` for more details on passing dynamic session variables.
 
 Next, let's setup some :doc:`basic access control rules <basics>`.
 

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

@@ -99,28 +99,24 @@ when we make GraphQL requests from an app or from a different service?
 Option 1: Development & Testing
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-While you're developing or testing, just indicate your role and your session variables by passing headers along with the request:
-
-.. image:: ../../../img/graphql/manual/auth/dev-mode-role-header.png
-
-If you've enabled Hasura GraphQL engine with an access key, make sure you add the ACCESS_KEY header as well.
-This will allow you to use Hasura GraphQL engine as if you were in development/testing mode. This is useful when
-you want to test against a Hasura GraphQL engine instance that is already serving a production application.
+While you're developing or testing, just indicate your role and your session variables by passing headers along with
+the request:
 
 .. image:: ../../../img/graphql/manual/auth/dev-mode-role-header-access-key.png
 
+.. note::
+
+  If you've enabled Hasura GraphQL engine with an access key, make sure you add the ACCESS_KEY header as well.
+
+
 Option 2: In production, from apps
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you're making GraphQL queries from your apps, you will not (and should not) be sending session variables directly from your app
-because anyone can spoof the role and values of the variables and get access to whatever data they want.
+If you're making GraphQL queries from your apps, you will probably not (and should not) be sending session variables directly
+from your app because anyone can spoof the role and values of the variables and get access to whatever data they want.
 
-In this case, you should configure a webhook that will return an object containing the role and session variables given the
-session token (authorization token, JWT, cookie etc.) that your app normally uses.
-
-Read more about :doc:`configuring webhook authentication for Hasura<webhook>`.
-
-There are four different types of operations for which you can define permissions on a table: Select, Insert,
-Update, and Delete.
+In this case, you should configure a webhook that will return an object containing the role and session variables
+given the session token (authorization token, JWT, cookie etc.) that your app normally uses.
 
+See :doc:`webhook` or :doc:`jwt` for more details on passing dynamic session variables in production.
 

docs/graphql/manual/auth/webhook.rst

@@ -6,8 +6,8 @@ Authorization using webhooks
   :depth: 2
   :local:
 
-You can configure a webhook to authenticate all incoming requests to the Hasura GraphQL engine server.
-See :doc:`GraphQL engine server options <../deployment/graphql-engine-flags/reference>` for details.
+You can configure a webhook (see :doc:`GraphQL engine server options <../deployment/graphql-engine-flags/reference>`)
+to authenticate all incoming requests to the Hasura GraphQL engine server.
 
 .. image:: ../../../img/graphql/manual/auth/webhook-auth.png
 

docs/graphql/manual/remote-schemas/index.rst

@@ -20,8 +20,8 @@ This is what Hasura running with "Remote schemas" looks like:
 
 .. note::
 
-  Note that is a new feature in active development. Please do give us feedback, bug-reports and ask
-  us questions on our `discord <https://discord.gg/vBPpJkS>`__ or on `github <https://github.com/hasura/graphql-engine>`__.
+  This is a new feature in active development. Please do give us feedback, bug-reports and ask us questions on
+  our `discord <https://discord.gg/vBPpJkS>`__ or on `github <https://github.com/hasura/graphql-engine>`__.
 
 Use-cases
 ---------
@@ -39,12 +39,10 @@ Note that if you are looking for adding authorization & access control for your
 app users to the GraphQL APIs that are auto-generated via Hasura, head to
 :doc:`Authorization / Access control <../auth/index>`
 
-.. note::
-
-   **Nomenclature**:
+.. admonition:: Nomenclature
 
    Top-level node names need to be unique across all merged schemas (*case-sensitive match*).
-   Types with the *exact same name and structure* will be merged. But types with *same name but different structure* will result in type conflicts.
+    Types with the *exact same name and structure* will be merged. But types with the *same name but different structure* will result in type conflicts.
 
 
 How to add a remote schema
@@ -64,9 +62,7 @@ is to use one of our boilerplates:
 - `Serverless boilerplates <https://github.com/hasura/graphql-serverless>`__
 
 
-.. note::
-
-  **Current limitations**:
+.. admonition:: Current limitations
 
   - Nodes from different GraphQL servers cannot be used in the same query/mutation. All top-level nodes have to be from the same GraphQL server.
   - Subscriptions on remote GraphQL server are not supported.

docs/graphql/manual/schema/basics.rst

@@ -29,6 +29,8 @@ Let's say we want to create two simple tables for an article/author schema:
     author_id INT
   )
 
+.. _create-tables:
+
 Create tables
 -------------
 

docs/graphql/manual/schema/enums.rst

@@ -42,6 +42,6 @@ using the fields: ``issue_month -> months_of_the_year :: month``:
 
 Now the ``issue_month`` field can only take values from the months of the year.
 
-.. note::
-  This will not provide auto-complete or query validation on the client side using the GraphQL schema as of now
-  but will ensure consistency in the database.
+.. admonition:: Current limitation
+
+  This does not generate GraphQL schema enums as of now but it ensures consistency in the database.