Merge pull request #215 from supabase/docs_kaizen

Docs Update
supabase · Oct 3, 2022 · bd02837 · bd02837
2 parents a83f0e3 + 96fae25
commit bd02837
Show file tree

Hide file tree

Showing 8 changed files with 1,369 additions and 158 deletions.
diff --git a/docs/api.md b/docs/api.md
diff --git a/docs/example_schema.md b/docs/example_schema.md
@@ -0,0 +1,9 @@
+The following is a complete example showing how a sample SQL schema translates into a GraphQL schema.
+
+```sql
+--8<-- "docs/assets/demo_schema.sql"
+```
+
+```graphql
+--8<-- "docs/assets/demo_schema.graphql"
+```
diff --git a/docs/index.md b/docs/index.md
@@ -19,13 +19,12 @@
 
 - [x] __Performant__
 - [x] __Consistent__
-- [x] __Serverless__
 - [x] __Open Source__
 
 ### Overview
-`pg_graphql` reflects a GraphQL schema from the existing SQL schema.
+`pg_graphql` is a PostgreSQL extension that enables querying the database with GraphQL using a single a SQL function.
 
-The extension keeps schema translation and query resolution neatly contained on your database server. This enables any programming language that can connect to PostgreSQL to query the database via GraphQL with no additional servers, processes, or libraries.
+The extension reflects a GraphQL schema from the existing SQL schema and exposes it through a SQL function, `graphql.resolve(...)`. This enables any programming language that can connect to PostgreSQL to query the database via GraphQL with no additional servers, processes, or libraries.
 
 
 ### TL;DR
@@ -63,6 +62,6 @@ create table blog_post(
 ```
 Translates into a GraphQL schema displayed below.
 
-Each table receives an entrypoint in the top level `Query` type that is a pageable collection with relationships defined by its foreign keys. Tables similarly recieve entrypoints in the `Mutation` schema that enable bulk operations for insert, update, and delete.
+Each table receives an entrypoint in the top level `Query` type that is a pageable collection with relationships defined by its foreign keys. Tables similarly recieve entrypoints in the `Mutation` type that enable bulk operations for insert, update, and delete.
 
 ![GraphiQL](./assets/quickstart_graphiql.png)
diff --git a/docs/performance.md b/docs/performance.md
diff --git a/docs/reflection.md b/docs/reflection.md
diff --git a/docs/requirements_docs.txt b/docs/requirements_docs.txt
@@ -1,2 +1,3 @@
 mkdocs
 mkdocs-material
+git+https://github.com/ivome/pygments-graphql-lexer.git
diff --git a/docs/sql_interface.md b/docs/sql_interface.md
@@ -0,0 +1,60 @@
+pg_graphql's public facing SQL interface consists of a single SQL function to resolve GraphQL requests. All other entities in the `graphql` schema are private.
+
+
+### graphql.resolve
+
+##### description
+Resolves a GraphQL query, returning JSONB.
+
+##### signature
+```sql
+graphql.resolve(
+    -- graphql query/mutation
+    query text,
+    -- json key/values pairs for variables
+    variables jsonb default '{}'::jsonb,
+    -- the name of the graphql operation in *query* to execute
+    "operationName" text default null,
+    -- extensions to include in the request
+    extensions jsonb default null,
+)
+    returns jsonb
+
+    strict
+    volatile
+    parallel safe
+    language plpgsql
+```
+
+##### usage
+
+```sql
+-- Create the extension
+graphqldb= create extension pg_graphql;
+CREATE EXTENSION
+
+-- Create an example table
+graphqldb= create table book(id int primary key, title text);
+CREATE TABLE
+
+-- Insert a record
+graphqldb= insert into book(id, title) values (1, 'book 1');
+INSERT 0 1
+
+-- Query the table via GraphQL
+graphqldb= select graphql.resolve($$
+query {
+  bookCollection {
+    edges {
+      node {
+        id
+      }
+    }
+  }
+}
+$$);
+
+             resolve
+----------------------------------------------------------------------
+{"data": {"bookCollection": {"edges": [{"node": {"id": 1}}]}}, "errors": []}
+```
diff --git a/mkdocs.yaml b/mkdocs.yaml
@@ -8,12 +8,12 @@ repo_url: https://github.com/supabase/pg_graphql
 nav:
     - Welcome: 'index.md'
     - Quickstart: 'quickstart.md'
+    - SQL Interface: 'sql_interface.md'
     - API: 'api.md'
-    - Reflection: 'reflection.md'
     - Computed Fields: 'computed_fields.md'
     - Security: 'security.md'
     - Configuration: 'configuration.md'
-    - Performance: 'performance.md'
+    - Example Schema: 'example_schema.md'
     - Installation: 'installation.md'
     - Contributing: 'contributing.md'
 
@@ -29,7 +29,12 @@ theme:
 markdown_extensions:
     - pymdownx.highlight:
         linenums: true
+        guess_lang: false
+        use_pygments: true
+        pygments_style: default
     - pymdownx.superfences
+    - pymdownx.tabbed:
+        alternate_style: true
     - pymdownx.snippets
     - pymdownx.tasklist
     - admonition