improve documentation (fix #745) (#746)

CONTRIBUTING.md

@@ -1,15 +1,15 @@
 # Contributing to Hasura graphql-engine
 
-*First*: if you're unsure or afraid of anything, just ask or submit the issue or
+*First*: if you're unsure or afraid of anything, just ask, or submit the issue or
 pull request anyway. You won't be yelled at for giving your best effort. The
 worst that can happen is that you'll be politely asked to change something. We
-appreciate any sort of contributions and don't want a wall of rules to get in
+appreciate any contributions, and we don't want a wall of rules to get in
 the way of that.
 
-However, for those individuals who want a bit more guidance on the best way to
+However, for individuals who want a bit more guidance on the best way to
 contribute to the project, read on. This document will cover what we're looking
-for. By addressing all the points we're looking for, it raises the chances we
-can quickly merge or address your contributions.
+for. By addressing all the points we're looking for, the chances that we
+can quickly merge or address your contributions will increase.
 
 
 ## Overview
@@ -24,7 +24,7 @@ consisting of 3 components. Each have their own contributing guides:
 All of the three components have a single version, denoted by either the git
 tag or a combination of branch name and git commit SHA.
 
-For all contributions, a CLA (Contributor License Agreement) needs to be signed [here](https://cla-assistant.io/hasura/graphql-engine) before (or after) the pull request has been submitted. A bot will prompt the same as a pull request comment.
+For all contributions, a CLA (Contributor License Agreement) needs to be signed [here](https://cla-assistant.io/hasura/graphql-engine) before (or after) the pull request has been submitted. A bot will prompt contributers to sign the CLA via a pull request comment, if necessary.
 
 
 ### Docs
@@ -38,7 +38,7 @@ help GraphQL Engine community/users can go into the section. We have identified
 [boilerplates](community/boilerplates), [examples](community/examples) and
 [tools](community/tools) as primary candidates. Feel free to submit a pull
 request if you have something to add (not necessarily belonging to the
-before-mentioned sections).
+aforementioned sections).
 
 ## Issues
 
@@ -48,7 +48,7 @@ before-mentioned sections).
   already fixed the bug you're experiencing.
 
 - Provide steps to reproduce the issue, including Postgres version,
-  graphql-engine version and the provider you are running on (Heroku, Docker
+  graphql-engine version and the provider you are running on (Heroku, Docker,
   etc.).
 
 - Please include logs of the server, if relevant.
@@ -69,15 +69,16 @@ before-mentioned sections).
 
 ## Commit messages
 
- - The first line should be a summary of the changes - not exceeding 50
-   characters. Followed by an optional body which has more details about the
-   changes. (https://github.com/erlang/otp/wiki/writing-good-commit-messages)
+- The first line should be a summary of the changes, not exceeding 50
+  characters, followed by an optional body which has more details about the
+  changes. Refer [to this link](https://github.com/erlang/otp/wiki/writing-good-commit-messages)
+  for more information on writing good commit messages.
 
- - Use the imperative present tense: "add/fix/change", not "added/fixed/changed" nor "adds/fixes/changes".
+- Use the imperative present tense: "add/fix/change", not "added/fixed/changed" nor "adds/fixes/changes".
 
- - Don't capitalize the first letter of the summary line.
+- Don't capitalize the first letter of the summary line.
 
- - Do not add a period/dot (.) at the end in the summary line.
+- Don't add a period/dot (.) at the end of the summary line.
 
 
 (Credits: Some sections are adapted from https://github.com/PostgREST/postgrest/blob/master/.github/CONTRIBUTING.md)

community/README.md

@@ -1,9 +1,9 @@
 # Community
 
-This directory contains community contributed code and content that supplements
+This directory contains community-contributed code and content that supplements
 Hasura GraphQL Engine. It includes several example applications built using
-GraphQL Engine to demonstrate it's features, several boilerplates for users to get
-started with auth webhooks, triggers etc. and some community tooling around the Engine.
+GraphQL Engine to demonstrate its features, several boilerplates for users to get
+started with auth webhooks, triggers, etc. and some community tooling around the Engine.
 
 Feel free to open pull requests to add more content here.
 

docs/CONTRIBUTING.md

@@ -1,8 +1,7 @@
 # Contributing
 
 [Sphinx](http://www.sphinx-doc.org/en/master/documentation) files are written in
-the RST markup language. Here is a [guide to RST markup
-language](http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
+the RST markup language. [Here]((http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)) is a guide to the RST markup language.
 
 ## Requirements
 
@@ -15,12 +14,12 @@ language](http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
   ```bash
   git clone https://github.com/<your-username>/graphql-engine
   ```
-- Move to `docs` folder and checkout to a new branch:
+- Move to the `docs` folder via the command line and checkout to a new branch:
   ```bash
   cd docs
   git checkout -b <new-branch-name>
   ```
-- Install dependencies (Sphinx, beautifulsoup4, algoliasearch, etc.)
+- Install dependencies:
   ```
   pip3 install -r requirements.txt
   ```
@@ -31,22 +30,21 @@ language](http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
   ```
 - Make the required changes.
 - (Optional) Build docs to produce HTML files and verify:
-    ```
+    ```bash
     ENV=<development|production> make html-images
     ```
-    * The generated docs are in `_build/html`. 
-    * View the built files by running a webserver. egg:
-        ```
+    - The generated docs are in `_build/html`. 
+    - View the built files by running a webserver:
+        ```bash
         cd _build/html && http-server
         ```
         or
 
-        ```
+        ```bash
         cd _build/html && python3 -m http.server 8080
         ```        
-- Commit the changes. Follow common guidelines for commit messages at [main
+- Commit the changes. Follow the common guidelines for commit messages at the [main
 contributing guide](../CONTRIBUTING.md#common-guidelines).
 - Push the changes to your fork and submit a pull request.
 
-**Note:** The search is powered by [Algolia](https://www.algolia.com/) and is updated on every deployment. Your local 
-  changes will not reflect in search results.        
+**Note:** The search is powered by [Algolia](https://www.algolia.com/) and is updated on every deployment. Your local changes will not be reflected in search results.        

docs/README.md

@@ -1,12 +1,12 @@
 # Hasura GraphQL Engine Docs
 
-The documentation accompanying Hasura GraphQL Engine: written using
+The documentation accompanying the Hasura GraphQL Engine is written with
 [Sphinx](http://www.sphinx-doc.org/en/master/) and deployed to
 [docs.hasura.io](https://docs.hasura.io).
 
 ## Contributing
 
-Checkout the [contributing](CONTRIBUTING.md) guide for more details.
+Check out the [contributing](CONTRIBUTING.md) guide for more details.
 
 ## License
 

docs/graphql/manual/auth/basics.rst

@@ -1,7 +1,7 @@
 Access control basics
 =====================
 
-In this section, we're going to setup a simple access control rule for restricting querying on a table.
+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 a author table
@@ -52,7 +52,7 @@ accepted with admin permissions.
 Add a simple access control rule for a logged in user
 -----------------------------------------------------
 
-Let's say for our app, logged in users are only allowed to fetch their own data.
+Let's say that for our app, logged in users are only allowed to fetch their own data.
 
 Let's add a **select** permission for the **user** role on the ``author`` table:
 
@@ -79,7 +79,7 @@ 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 2 dynamic authorization variables via request headers.
+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.
 
 .. image:: ../../../img/graphql/manual/auth/query-with-perms.png
@@ -102,8 +102,7 @@ Head to the ``Permissions`` tab of the table and edit the ``Select`` permissions
 Limit number of rows returned in a single request
 -------------------------------------------------
 
-We can set a hard limit on the maximum number of rows that will be returned in a single request for a table for a
-particular role.
+We can set a hard limit on the maximum number of rows that will be returned in a single request for a table for a particular role.
 
 Head to the ``Permissions`` tab of the table and edit the ``Select`` permissions for the role:
 

docs/graphql/manual/auth/common-roles-auth-examples.rst

@@ -9,10 +9,10 @@ Anonymous (not logged in) users
 -------------------------------
 
 - Create a role called ``anonymous`` (this value is up to you, you could even name the role ``public``).
-- Generally, you wouldn't add insert, update or delete permissions.
-- For the select permission condition setup a valid condition depending on your data model. For example, ``is_published: {_eq: true}``.
-- If you don't have a condition, then just set the permission to ``Without any checks`` represented by a ``{}``.
-- Choose the right set of columns that will get exposed in the GraphQL schema as fields. Take care of not exposing sensitive information.
+- Generally, you wouldn't add insert, update, or delete permissions.
+- For the select permission condition, create a valid condition depending on your data model. For example, ``is_published: {_eq: true}``.
+- If you don't have a condition, then just set the permission to ``Without any checks``, represented by a ``{}``.
+- Choose the right set of columns that will get exposed in the GraphQL schema as fields. Ensure that sensitive information will not be exposed.
 
 .. image:: ../../../img/graphql/manual/auth/anonymous-role-examples.png
    :class: no-shadow
@@ -22,7 +22,7 @@ Logged-in users
 
 - Create a role called ``user``.
 - Access control rules in this case are usually dependent on a ``user_id`` or a ``owner_id`` column in your data model.
-- Setup a permission for insert/select/update/delete that uses said column. E.g.: ``author_id: {_eq: "X-Hasura-User-Id"}`` for an article table.
+- Set up a permission for insert/select/update/delete that uses said column. E.g.: ``author_id: {_eq: "X-Hasura-User-Id"}`` for an article table.
 - Note that the ``X-Hasura-User-Id`` is a :doc:`dynamic session variable<./roles-variables>` that comes in from your :doc:`auth webhook's<./webhook>` response, or as a request as a header if you're testing.
 
 .. image:: ../../../img/graphql/manual/auth/user-select-graphiql.png
@@ -46,7 +46,7 @@ Collaborators of an article
 
 Let's say the "ownership" or "visibility" information for a data model (table) is not present as a column in the table, but in a different related table. In this case, let's say there is an ``article`` table and a ``collaborator`` table that has ``article_id, collaborator_id`` columns.
 
-- Create a relationship called collaborators from the article table.
+- Create a relationship called ``collaborators`` from the article table.
 
   - Array relationship (article has array of collaborators): ``article :: id → collaborator :: article_id``.
 
@@ -58,15 +58,15 @@ Let's say the "ownership" or "visibility" information for a data model (table) i
 .. image:: ../../../img/graphql/manual/auth/collaborator-relationship.png
    :class: no-shadow
 
-Role based schemas
+Role-based schemas
 ------------------
 
-For every role that you create, Hasura automatically publishes a different GraphQL schema that represents the right queries, fields and mutations that are available to that role.
+For every role that you create, Hasura automatically publishes a different GraphQL schema that represents the right queries, fields, and mutations that are available to that role.
 
 Case 1: Logged-in users and anonymous users can access the same GraphQL fields
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In simple use-cases logged-in users and anonymous users might be able to fetch different rows (let's say because of a ``is_public`` flag) but have access to the same fields.
+In simple use-cases, logged-in users and anonymous users might be able to fetch different rows (let's say because of a ``is_public`` flag), but have access to the same fields.
 
 - ``anonymous`` role has a ``{is_public: {_eq: true}}`` select condition.
 

docs/graphql/manual/auth/index.rst

@@ -15,7 +15,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
+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.

docs/graphql/manual/auth/jwt.rst

@@ -12,7 +12,7 @@ verified by GraphQL engine to authorize and get metadata about the request
 
 .. image:: ../../../img/graphql/manual/auth/jwt-auth.png
 
-The JWT is decoded, the signature is verified and then it is asserted that the
+The JWT is decoded, the signature is verified, then it is asserted that the
 current role of the user is in the list of allowed roles. If the authorization
 passes, then all of the ``x-hasura-*`` values in the claim is used for the
 permissions system.

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

@@ -107,15 +107,15 @@ you want to test against a Hasura GraphQL engine instance that is already servin
 Option 2: In production, from apps
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you're making GraphQL queries from your apps, you will not (should not) be sending session variables directly from your app
+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.
 
 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 4 different types of operations for which you can define permissions on a table: Select, Insert,
-Update and Delete.
+There are four different types of operations for which you can define permissions on a table: Select, Insert,
+Update, and Delete.
 
 

docs/graphql/manual/getting-started/docker-simple.rst

@@ -2,10 +2,10 @@ Quickstart with Docker
 ======================
 
 This guide will help you get Hasura GraphQL engine and Postgres running as
-Docker containers using Docker Compose. This is the easiest way of setting up
+Docker containers using Docker Compose. This is the easiest way to set up
 Hasura GraphQL engine on your **local environment**. 
 
-In case, you'd like to run Hasura on an existing Postgres database, follow this
+In case you'd like to run Hasura on an existing Postgres database, follow this
 guide to :doc:`deploy the Hasura GraphQL engine as a standalone docker container
 <../deployment/docker/index>` and connect it to your Postgres instance. 
 
@@ -45,7 +45,7 @@ Check if the containers are running:
 Step 3: Open the Hasura console
 -------------------------------
 
-Head to http://localhost:8080/console to open the Hasura console.
+Head to ``http://localhost:8080/console`` to open the Hasura console.
 
 Next: Try Hasura out!
 ---------------------

docs/requirements.txt

@@ -18,17 +18,17 @@ port-for==0.3.1
 Pygments==2.2.0
 pytz==2017.2
 PyYAML==3.13
-requests==2.18.4
 requests-file==1.4.2
+requests==2.18.4
 six==1.11.0
 snowballstemmer==1.2.1
-Sphinx==1.6.5
 sphinx-autobuild==0.7.1
+Sphinx==1.6.5
+sphinx_tabs==1.1.7
 sphinxcontrib-fulltoc==1.2.0
-sphinxcontrib-httpdomain==1.5.0
+sphinxcontrib-httpdomain==1.7.0
 sphinxcontrib-swaggerdoc==0.1.7
 sphinxcontrib-websupport==1.0.1
 tornado==4.5.2
 urllib3==1.22
 watchdog==0.8.3
-sphinx_tabs==1.1.7

server/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing
 
-This guide is for setting-up the graphql-engine server for development on your
-own machine, and how to contribute.
+This guide explains how to set up the graphql-engine server for development on your
+own machine and how to contribute.
 
 ## Pre-requisites