Docs remove custom intro pages (#8358)

geldata · Feb 21, 2025 · 780061d · 780061d
1 parent 14536d2
commit 780061d
Show file tree

Hide file tree

Showing 13 changed files with 282 additions and 11 deletions.
diff --git a/docs/guides/auth/built_in_ui.rst → docs/auth/built_in_ui.rst b/docs/guides/auth/built_in_ui.rst → docs/auth/built_in_ui.rst
diff --git a/docs/guides/auth/email_password.rst → docs/auth/email_password.rst b/docs/guides/auth/email_password.rst → docs/auth/email_password.rst
diff --git a/docs/guides/auth/images/ui-auth.png → docs/auth/images/ui-auth.png b/docs/guides/auth/images/ui-auth.png → docs/auth/images/ui-auth.png
diff --git a/docs/guides/auth/index.rst → docs/auth/index.rst b/docs/guides/auth/index.rst → docs/auth/index.rst
diff --git a/docs/guides/auth/magic_link.rst → docs/auth/magic_link.rst b/docs/guides/auth/magic_link.rst → docs/auth/magic_link.rst
diff --git a/docs/guides/auth/oauth.rst → docs/auth/oauth.rst b/docs/guides/auth/oauth.rst → docs/auth/oauth.rst
diff --git a/docs/guides/auth/webauthn.rst → docs/auth/webauthn.rst b/docs/guides/auth/webauthn.rst → docs/auth/webauthn.rst
diff --git a/docs/cloud/index.rst b/docs/cloud/index.rst
@@ -6,13 +6,6 @@ Cloud
 
 :edb-alt-title: Using Gel Cloud
 
-|Gel| Cloud is the easiest way to host your Gel instance. We offer two ways
-to interact with Gel Cloud: via our CLI or through a graphical web
-interface nearly identical to the :ref:`Gel UI <ref_cli_gel_ui>`.
-
-.. edb:youtube-embed:: IG1MggUzzH4
-
-
 .. toctree::
     :maxdepth: 2
     :hidden:
@@ -27,11 +20,134 @@ interface nearly identical to the :ref:`Gel UI <ref_cli_gel_ui>`.
     deploy/render
     deploy/railway
 
+
+|Gel| Cloud is a fully managed, effortless cloud database service,
+engineered to let you deploy your database instantly and connect from
+anywhere with near-zero configuration.
+
+Connecting your app
+===================
+
+Try a guide for connecting your app running on your platform of choice:
+
+.. TODO: render these with icons
+
+* :ref:`Vercel <ref_guide_cloud_deploy_vercel>`
+* :ref:`Netlify <ref_guide_cloud_deploy_netlify>`
+* :ref:`Fly.io <ref_guide_cloud_deploy_fly>`
+* :ref:`Render <ref_guide_cloud_deploy_render>`
+* :ref:`Railway <ref_guide_cloud_deploy_railway>`
+
+
+To connect your apps running on other platforms, generate a dedicated
+secret key for your instance with :gelcmd:`cloud secretkey create` or via the
+web UI's “Secret Keys” pane in your instance dashboard. Create two environment
+variables accessible to your production application:
+
+* :gelenv:`SECRET_KEY` - contains the secret key you generated
+* :gelenv:`INSTANCE` - the name of your |Gel| Cloud instance (``<org-name>/<instance-name>``)
+
+.. edb:youtube-embed:: IG1MggUzzH4
+
+
+Two ways to use Gel Cloud
+=========================
+
+1. CLI
+^^^^^^
+
+Log in to |Gel| Cloud via the CLI:
+
+.. code-block:: bash
+
+  $ gel cloud login
+
+
+This will open a browser window and allow you to log in via GitHub.
+Now, create your |Gel| Cloud instance the same way you would create a
+local instance:
+
+.. code-block:: bash
+
+  $ gel instance create <org-name>/<instance-name>
+
+or
+
+.. code-block:: bash
+
+  $ gel project init \
+  --server-instance <org-name>/<instance-name>
+
+
+2. GUI
+^^^^^^
+
+Create your instance at `cloud.geldata.com <https://cloud.geldata.com>`_ by
+clicking on “Create new instance” in the “Instances” tab.
+
+.. <div className={styles.cloudGuiImg} />
+
+Complete the following form to configure your instance. You can access
+your instance via the CLI using the name ``<org-name>/<instance-name>`` or via the GUI.
+
+
+Useful Gel Cloud commands
+=========================
+
+Get REPL
+^^^^^^^^
+
+.. code-block:: bash
+
+  $ gel \
+    -I <org-name>/<instance-name>
+
+Run migrations
+^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  $ gel migrate \
+    -I <org-name>/<instance-name>
+
+Update your instance
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  $ gel instance upgrade \
+    --to-version <target-version> \
+    -I <org-name>/<instance-name>
+
+Manual full backup
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  $ gel dump \
+    --all --format dir \
+    -I <org-name>/<instance-name> \
+    <local-dump-path>
+
+Full restore
+^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  $ gel restore \
+    --all \
+    -I <org-name>/<instance-name> \
+    <local-dump-path>
+
+.. note::
+
+  Restoring works only to an empty database.
+
 
 Questions? Problems? Bugs?
 ==========================
 
-Thank you for helping us make the best way to host your Gel instances even
+Thank you for helping us make the best way to host your |Gel| instances even
 better!
 
 * Please join us on `our Discord <https://discord.gg/umUueND6ag>`_  to ask
@@ -43,4 +159,4 @@ better!
   <https://www.geldata.com/p/cloud-support>`_. Note: when using |Gel| Cloud
   through the CLI, setting the ``RUST_LOG`` environment variable to ``info``,
   ``debug``, or ``trace`` may provide additional debugging information
-  which will be useful to include with your ticket.
+  which will be useful to include with your ticket.
diff --git a/docs/guides/index.rst b/docs/guides/index.rst
@@ -18,6 +18,5 @@ guide!
     deployment/index
     datamigrations/index
     tutorials/index
-    auth/index
     migrations/index
     contributing/index
diff --git a/docs/index.rst b/docs/index.rst
@@ -16,6 +16,7 @@ Welcome to the |Gel| |version| documentation.
     intro/index
     datamodel/index
     ai/index
+    auth/index
     edgeql/index
     guides/index
     stdlib/index
@@ -25,3 +26,6 @@ Welcome to the |Gel| |version| documentation.
     cheatsheets/index
     changelog/index
     cloud/index
+
+    reference-intro
+    resources-intro
diff --git a/docs/intro/index.rst b/docs/intro/index.rst
@@ -120,7 +120,7 @@ EdgeQL.
   deployment guides for all major cloud hosting platforms, as well as
   instructions for self-hosting with Docker.
 
-.. eql:react-element:: DocsNavTable
+.. .. eql:react-element:: DocsNavTable
 
 |Gel| features:
 

diff --git a/docs/reference-intro.rst b/docs/reference-intro.rst
@@ -0,0 +1,149 @@
+=========
+Reference
+=========
+
+Learn three components, and you know |Gel|: how to work with
+:ref:`schema <ref_datamodel_index>`, how to write queries with
+:ref:`EdgeQL <ref_edgeql>`, and what's available to you in our
+:ref:`standard library <ref_std>`. Start in those sections if you're new to |Gel|.
+Move over to our :ref:`reference <ref_reference_index>` when you're ready to
+dive deep into the internals, syntax, and other advanced topics.
+
+
+Schema
+------
+
+|Gel| schemas are declared using our schema definition language (SDL).
+
+.. code-block:: sdl
+
+  module default {
+    type Book {
+      required title: str;
+      release_year: int16;
+      author: Person;
+    }
+    type Person {
+      required name: str;
+    }
+  }
+   
+The example schema above defines two types: Book and Person, each with
+a property or two. Book also contains a link to the author, which is a
+link to objects of the Person type. Learn more about how to define
+your schema using SDL in the :ref:`schema <ref_datamodel_index>` section.
+
+
+EdgeQL
+------
+
+EdgeQL is a next-generation query language designed to match SQL in power and
+surpass it in terms of clarity, brevity, and intuitiveness.
+
+.. code-block:: edgeql-repl
+
+  db> select Book {
+  ...   title,
+  ...   release_year,
+  ...   author: {
+  ...     name
+  ...   }
+  ... } order by .title;
+  {
+    default::Book {
+      title: '1984',
+      release_year: 1949,
+      author: default::Person {
+        name: 'George Orwell'
+      }
+    },
+    default::Book {
+      title: 'Americanah',
+      release_year: 2013,
+      author: default::Person {
+        name: 'Chimamanda Ngozi Adichie'
+      }
+    },
+    ...
+  }
+
+You can use EdgeQL to easily return nested data structures just by putting a
+shape with a link on an object as shown above.
+
+
+Standard library
+----------------
+
+|Gel| comes with a rigorously defined type system consisting of scalar
+types, collection types (like arrays and tuples), and object types. It
+also includes a library of built-in functions and operators for working
+with each datatype, alongside some additional utilities and extensions.
+
+.. code-block:: edgeql-repl
+
+  db> select count(Book);
+  {16}
+  db> select Book {
+  ...   title,
+  ...   title_length := len(.title)
+  ... } order by .title_length;
+  {
+    default::Book {
+      title: 'Sula',
+      title_length: 4
+    },
+    default::Book {
+      title: '1984',
+      title_length: 4
+    },
+    default::Book {
+      title: 'Beloved',
+      title_length: 7
+    },
+    default::Book {
+      title: 'The Fellowship of the Ring',
+      title_length: 26
+    },
+    default::Book {
+      title: 'One Hundred Years of Solitude',
+      title_length: 29
+    },
+  }
+  db> select math::stddev(len(Book.title));
+  {7.298401651503339}
+
+Gel comes with a rigorously defined type system consisting of scalar
+types, collection types (like arrays and tuples), and object types. It
+also includes a library of built-in functions and operators for working
+with each datatype, alongside some additional utilities and extensions.
+
+
+Cheatsheets
+-----------
+
+Learn to do various common tasks using the many tools included with |Gel|.
+
+Querying
+^^^^^^^^
+
+* :ref:`Select <ref_cheatsheet_select>`
+* :ref:`Insert <ref_cheatsheet_insert>`
+* :ref:`Update <ref_cheatsheet_update>`
+* :ref:`Delete <ref_cheatsheet_delete>`
+* :ref:`via GraphQL <ref_cheatsheet_graphql>`
+
+Schema
+^^^^^^
+
+* :ref:`Booleans <ref_cheatsheet_boolean>`
+* :ref:`Object Types <ref_cheatsheet_object_types>`
+* :ref:`Functions <ref_cheatsheet_functions>`
+* :ref:`Aliases <ref_cheatsheet_aliases>`
+* :ref:`Annotations <ref_cheatsheet_annotations>`
+* :ref:`Link Properties <ref_datamodel_linkprops>`
+
+Admin
+^^^^^
+* :ref:`CLI <ref_cheatsheet_cli>`
+* :ref:`REPL <ref_cheatsheet_select>`
+* :ref:`Admin <ref_cheatsheet_admin>`
diff --git a/docs/resources-intro.rst b/docs/resources-intro.rst
@@ -0,0 +1,3 @@
+=========
+Resources
+=========