From 780061dd14f04e9c4bfa6607bc40fa76d5e28a90 Mon Sep 17 00:00:00 2001 From: James Clarke Date: Thu, 20 Feb 2025 17:43:14 +0000 Subject: [PATCH] Docs remove custom intro pages (#8358) --- docs/{guides => }/auth/built_in_ui.rst | 0 docs/{guides => }/auth/email_password.rst | 0 docs/{guides => }/auth/images/ui-auth.png | Bin docs/{guides => }/auth/index.rst | 0 docs/{guides => }/auth/magic_link.rst | 0 docs/{guides => }/auth/oauth.rst | 0 docs/{guides => }/auth/webauthn.rst | 0 docs/cloud/index.rst | 134 +++++++++++++++++-- docs/guides/index.rst | 1 - docs/index.rst | 4 + docs/intro/index.rst | 2 +- docs/reference-intro.rst | 149 ++++++++++++++++++++++ docs/resources-intro.rst | 3 + 13 files changed, 282 insertions(+), 11 deletions(-) rename docs/{guides => }/auth/built_in_ui.rst (100%) rename docs/{guides => }/auth/email_password.rst (100%) rename docs/{guides => }/auth/images/ui-auth.png (100%) rename docs/{guides => }/auth/index.rst (100%) rename docs/{guides => }/auth/magic_link.rst (100%) rename docs/{guides => }/auth/oauth.rst (100%) rename docs/{guides => }/auth/webauthn.rst (100%) create mode 100644 docs/reference-intro.rst create mode 100644 docs/resources-intro.rst diff --git a/docs/guides/auth/built_in_ui.rst b/docs/auth/built_in_ui.rst similarity index 100% rename from docs/guides/auth/built_in_ui.rst rename to docs/auth/built_in_ui.rst diff --git a/docs/guides/auth/email_password.rst b/docs/auth/email_password.rst similarity index 100% rename from docs/guides/auth/email_password.rst rename to docs/auth/email_password.rst diff --git a/docs/guides/auth/images/ui-auth.png b/docs/auth/images/ui-auth.png similarity index 100% rename from docs/guides/auth/images/ui-auth.png rename to docs/auth/images/ui-auth.png diff --git a/docs/guides/auth/index.rst b/docs/auth/index.rst similarity index 100% rename from docs/guides/auth/index.rst rename to docs/auth/index.rst diff --git a/docs/guides/auth/magic_link.rst b/docs/auth/magic_link.rst similarity index 100% rename from docs/guides/auth/magic_link.rst rename to docs/auth/magic_link.rst diff --git a/docs/guides/auth/oauth.rst b/docs/auth/oauth.rst similarity index 100% rename from docs/guides/auth/oauth.rst rename to docs/auth/oauth.rst diff --git a/docs/guides/auth/webauthn.rst b/docs/auth/webauthn.rst similarity index 100% rename from docs/guides/auth/webauthn.rst rename to docs/auth/webauthn.rst diff --git a/docs/cloud/index.rst b/docs/cloud/index.rst index fab2d84cc05..ed476153647 100644 --- 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 `. - -.. edb:youtube-embed:: IG1MggUzzH4 - - .. toctree:: :maxdepth: 2 :hidden: @@ -27,11 +20,134 @@ interface nearly identical to the :ref:`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:`Netlify ` +* :ref:`Fly.io ` +* :ref:`Render ` +* :ref:`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 (``/``) + +.. 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 / + +or + +.. code-block:: bash + + $ gel project init \ + --server-instance / + + +2. GUI +^^^^^^ + +Create your instance at `cloud.geldata.com `_ by +clicking on “Create new instance” in the “Instances” tab. + +..
+ +Complete the following form to configure your instance. You can access +your instance via the CLI using the name ``/`` or via the GUI. + + +Useful Gel Cloud commands +========================= + +Get REPL +^^^^^^^^ + +.. code-block:: bash + + $ gel \ + -I / + +Run migrations +^^^^^^^^^^^^^^ + +.. code-block:: bash + + $ gel migrate \ + -I / + +Update your instance +^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + $ gel instance upgrade \ + --to-version \ + -I / + +Manual full backup +^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + $ gel dump \ + --all --format dir \ + -I / \ + + +Full restore +^^^^^^^^^^^^ + +.. code-block:: bash + + $ gel restore \ + --all \ + -I / \ + + +.. 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 `_ to ask @@ -43,4 +159,4 @@ better! `_. 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. \ No newline at end of file diff --git a/docs/guides/index.rst b/docs/guides/index.rst index 7d0b1da2186..3df06fe3573 100644 --- 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 index ce82fdc02ad..510ad9c072e 100644 --- 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 index 1a2bf8edcb2..ef0a93f337b 100644 --- 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 new file mode 100644 index 00000000000..40a9f852f7c --- /dev/null +++ b/docs/reference-intro.rst @@ -0,0 +1,149 @@ +========= +Reference +========= + +Learn three components, and you know |Gel|: how to work with +:ref:`schema `, how to write queries with +:ref:`EdgeQL `, and what's available to you in our +:ref:`standard library `. Start in those sections if you're new to |Gel|. +Move over to our :ref:`reference ` 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 ` 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:`Insert ` +* :ref:`Update ` +* :ref:`Delete ` +* :ref:`via GraphQL ` + +Schema +^^^^^^ + +* :ref:`Booleans ` +* :ref:`Object Types ` +* :ref:`Functions ` +* :ref:`Aliases ` +* :ref:`Annotations ` +* :ref:`Link Properties ` + +Admin +^^^^^ +* :ref:`CLI ` +* :ref:`REPL ` +* :ref:`Admin ` \ No newline at end of file diff --git a/docs/resources-intro.rst b/docs/resources-intro.rst new file mode 100644 index 00000000000..afce060172e --- /dev/null +++ b/docs/resources-intro.rst @@ -0,0 +1,3 @@ +========= +Resources +========= \ No newline at end of file