update docs (#1748)

* increase roles TOC depth
* update enum docs page
* open external links in docs in new tabs
* update nested object sort docs

docs/_theme/djangodocs/layout.html

@@ -521,5 +521,15 @@
     });
   </script>
 
+  <!-- open external links in new tab -->
+  <script type="text/javascript">
+    $(document).ready( function() {
+      const externalLinks = $('a.reference.external');
+      for (let i = 0; i < externalLinks.length; i++) {
+        externalLinks[i].setAttribute('target', '_blank');
+      }
+    });
+  </script>
+
   {%- block extrafooter %} {% endblock %}
 {% endblock %}

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

@@ -3,7 +3,7 @@ Roles & Session variables
 
 .. contents:: Table of contents
   :backlinks: none
-  :depth: 1
+  :depth: 2
   :local:
 
 The permissions system offered by Hasura GraphQL engine is extremely flexible and is built to capture complex
@@ -96,8 +96,8 @@ 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
 when we make GraphQL requests from an app or from a different service?
 
-Option 1: Development & Testing
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For Development & Testing
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 While you're developing or testing, just indicate your role and your session variables by passing headers along with
 the request:
@@ -110,8 +110,8 @@ the request:
   header as well.
 
 
-Option 2: In production, from apps
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In Production, from apps
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 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

docs/graphql/manual/deployment/graphql-engine-flags/reference.rst

@@ -158,4 +158,5 @@ For ``serve`` sub-command these are the flags and ENV variables available:
        (default: ``metadata,graphql``)
 
 .. note::
-  1. When the equivalent flags for environment variables are used, the flags will take precedence.
+
+  When the equivalent flags for environment variables are used, the flags will take precedence.

docs/graphql/manual/queries/sorting.rst

@@ -19,8 +19,8 @@ ascending ordering by specifying ``asc_nulls_first`` and last on descending orde
 
 The ``order_by`` argument takes an array of objects to allow sorting by multiple columns.
 
-You can also use nested objects' fields to sort the results. Only columns from **object relationships** and
-are aggregates from **array relationships** can be used for sorting.
+You can also use nested objects' fields to sort the results. Only **columns from object relationships** and
+**aggregates from array relationships** can be used for sorting.
 
 You can see the complete specification of the ``order_by`` argument in the :ref:`API reference <OrderByExp>`.
 
@@ -76,7 +76,8 @@ Fetch list of authors sorted by their names in an ascending order:
 
 Sorting nested objects
 ----------------------
-Fetch a list of authors sorted by their names with a list of their articles that is sorted by their rating:
+**Example:** Fetch a list of authors sorted by their names with a list of their articles that is sorted by
+their rating:
 
 .. graphiql::
   :view_only:
@@ -155,9 +156,13 @@ Fetch a list of authors sorted by their names with a list of their articles that
 
 Sorting based on nested object's fields
 ---------------------------------------
-Only columns in object relationships can be used for sorting.
+Only **columns from object relationships** and **aggregates from array relationships** can be used for sorting.
 
-Fetch a list of articles that are sorted by their author ids in descending:
+For Object relationships
+^^^^^^^^^^^^^^^^^^^^^^^^
+For object relationships only columns can be used for sorting.
+
+**Example:** Fetch a list of articles that are sorted by their author's ids in descending:
 
 .. graphiql::
   :view_only:
@@ -210,18 +215,20 @@ Fetch a list of articles that are sorted by their author ids in descending:
       }
     }
 
-Sorting based on nested objects' aggregates
--------------------------------------------
-Only aggregates in array relationships can be used for sorting.
+For Array relationships
+^^^^^^^^^^^^^^^^^^^^^^^
+For array relationships only aggregates can be used for sorting.
 
-Fetch a list of authors sorted by their article count in descending.
+**Example:** Fetch a list of authors sorted in descending order of their article count:
 
 .. graphiql::
   :view_only:
   :query:
     query {
       author (
-        order_by: {articles_aggregate: {count: desc}}
+        order_by: {
+          articles_aggregate: {count: desc}
+        }
       ) {
         id
         name
@@ -267,11 +274,107 @@ Fetch a list of authors sorted by their article count in descending.
       }
     }
 
+**Example:** Fetch a list of authors sorted in increasing order of their highest article rating:
+
+.. graphiql::
+  :view_only:
+  :query:
+    query {
+      author(
+        order_by: {
+          articles_aggregate: {
+            max: {rating: asc_nulls_last}
+          }
+        }
+      ) {
+        id
+        name
+        articles_aggregate {
+          aggregate{
+            max {rating}
+          }
+        }
+      }
+    }
+  :response:
+    {
+      "data": {
+        "author": [
+          {
+            "id": 7,
+            "name": "Berti",
+            "articles_aggregate": {
+              "aggregate": {
+                "max": {
+                  "rating": 2
+                }
+              }
+            }
+          },
+          {
+            "id": 2,
+            "name": "Beltran",
+            "articles_aggregate": {
+              "aggregate": {
+                "max": {
+                  "rating": 3
+                }
+              }
+            }
+          },
+          {
+            "id": 8,
+            "name": "April",
+            "articles_aggregate": {
+              "aggregate": {
+                "max": {
+                  "rating": 4
+                }
+              }
+            }
+          },
+          {
+            "id": 3,
+            "name": "Sidney",
+            "articles_aggregate": {
+              "aggregate": {
+                "max": {
+                  "rating": 4
+                }
+              }
+            }
+          },
+          {
+            "id": 5,
+            "name": "Amii",
+            "articles_aggregate": {
+              "aggregate": {
+                "max": {
+                  "rating": 5
+                }
+              }
+            }
+          },
+          {
+            "id": 9,
+            "name": "Ninnetta",
+            "articles_aggregate": {
+              "aggregate": {
+                "max": {
+                  "rating": null
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+
 
 Sorting by multiple fields
 --------------------------
-Fetch a list of articles that is sorted by their rating (descending) and then on their published date (ascending with
-nulls first):
+**Example:** Fetch a list of articles that is sorted by their rating (descending) and then on their published
+date (ascending with nulls first):
 
 .. graphiql::
   :view_only:

docs/graphql/manual/schema/enums.rst

@@ -8,16 +8,76 @@ Enum type fields
 
 Enum type fields can only take a value from a fixed set of allowed values.
 
-In a relational database such as Postgres, an enum type field in a table can be defined by setting a foreign-key
-to another table which contains the reference list of allowed values. This ensures a value can be set into the field
-only if it exists in the reference table.
+In a relational database such as Postgres, an enum type field in a table can be defined by:
+
+- using native database enum types
+- setting a foreign-key to a reference table which contains the list of allowed values.
+
+`Postgres Enum types <https://www.postgresql.org/docs/current/datatype-enum.html>`__ are not easily mutable. Hence
+they should be used only for enums which are not going to change over time. e.g. measurement units, days of the
+week, etc.
+
+For enums whose values are dynamic and will require updates, the reference table approach is recommended. e.g. list
+of tags, list of teams, etc.
+
+.. admonition:: Current limitations
+
+  Hasura currently does not generate GraphQL enums. This feature is being worked upon. Hence this guide is currently
+  only tailored towards helping you maintain data consistency in your database
+
 
 **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 (i.e. January,
 February, and so on).
 
+The following are the approaches we can use to achieve this:
+
+Option 1: Using native Postgres enum type
+-----------------------------------------
+
+Create a Postgres enum type
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Open the Hasura console and head to the ``Data -> SQL`` interface.
+
+Run the following SQL statement:
+
+.. code-block:: sql
+
+  CREATE TYPE month AS ENUM ('January', 'February', 'March', 'and so on...');
+
+Set column type as the Postgres enum type
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Run the following SQL statement if the table doesn't yet exist:
+
+.. code-block:: sql
+  :emphasize-lines: 4
+
+  CREATE TABLE magazine(
+    id serial PRIMARY KEY,
+    title text NOT NULL,
+    issue_month month,
+    issue_year integer
+  );
+
+If table exists, run the following SQL statement:
+
+.. code-block:: sql
+
+  ALTER TABLE magazine
+    ALTER COLUMN issue_month TYPE month using issue_month::month;
+
+
+Now the ``issue_month`` field can only take values from the months of the year.
+
+See `Postgres Enum types documentation <https://www.postgresql.org/docs/current/datatype-enum.html>`__ for more info.
+
+Option 2: Using a reference table
+---------------------------------
+
 Create a reference table for the enum
--------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Open the Hasura console and head to the ``Data -> Create table`` interface.
 
@@ -26,14 +86,14 @@ Create a table ``months_of_the_year`` with just one column ``month``, which is t
 .. thumbnail:: ../../../img/graphql/manual/schema/enum-create-ref-table.png
 
 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:
 
 .. thumbnail:: ../../../img/graphql/manual/schema/enum-insert-ref-values.png
 
 Add a foreign-key constraint to the reference table
----------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 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``:
@@ -41,7 +101,3 @@ using the fields: ``issue_month -> months_of_the_year :: month``:
 .. thumbnail:: ../../../img/graphql/manual/schema/enum-set-foreign-key.png
 
 Now the ``issue_month`` field can only take values from the months of the year.
-
-.. admonition:: Current limitation
-
-  This does not generate GraphQL schema enums as of now but it ensures consistency in the database.

docs/graphql/manual/schema/views.rst

@@ -27,7 +27,7 @@ Creating views
 Views can be created using SQL which can be run in the Hasura console:
 
 - Head to the ``Data -> SQL`` section of the Hasura console
-- Enter your `create view SQL statement <https://www.postgresql.org/docs/9.6/static/sql-createview.html>`__
+- Enter your `create view SQL statement <https://www.postgresql.org/docs/current/static/sql-createview.html>`__
 - Select the ``Track this`` checkbox to expose the new view over the GraphQL API
 - Hit the ``Run`` button