From eb314789a0c840df32802cda36b1d2411ba11918 Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Wed, 19 Feb 2025 22:49:01 -0800 Subject: [PATCH 1/6] Drop reference/ddl --- docs/datamodel/index.rst | 9 +++++-- docs/datamodel/migrations.rst | 6 +++++ docs/reference/ddl/index.rst | 46 ----------------------------------- docs/reference/index.rst | 1 - 4 files changed, 13 insertions(+), 49 deletions(-) delete mode 100644 docs/reference/ddl/index.rst diff --git a/docs/datamodel/index.rst b/docs/datamodel/index.rst index afc7393ddb0..0dc7824db4d 100644 --- a/docs/datamodel/index.rst +++ b/docs/datamodel/index.rst @@ -76,8 +76,8 @@ Example: `Atom `_, and `Vim `_. -Migrations ----------- +Migrations and DDL +------------------ Gel's baked-in migration system lets you painlessly evolve your schema over time. Just update the contents of your |.gel| file(s) and use the |Gel| CLI @@ -90,6 +90,11 @@ to *create* and *apply* migrations. $ gel migrate Applied dbschema/migrations/00001.edgeql +Migrations are sequences of *data definition language* (DDL) commands. +DDL is a low level language that tells the database how exactly to change +the schema. Don't worry, you won't need to write any DDL directly, the Gel +server will generate it for you. + For a full guide on migrations, refer to the :ref:`Creating and applying migrations ` guide or the :ref:`migrations reference ` section. diff --git a/docs/datamodel/migrations.rst b/docs/datamodel/migrations.rst index 626c95923e3..9b941e8a536 100644 --- a/docs/datamodel/migrations.rst +++ b/docs/datamodel/migrations.rst @@ -77,6 +77,7 @@ For this use case you can use the :gelcmd:`watch` command, which will monitor your |.gel| files and automatically create and apply migrations for you in the background. +.. _ref_eql_ddl: Data definition language (DDL) ============================== @@ -84,6 +85,11 @@ Data definition language (DDL) The migration plan is a sequence of DDL commands. DDL commands are low-level instructions that describe the changes to the schema. +SDL and your |.gel| files are like a 3D printer: you design the final shape, +and the system puts a database together for you. Using DDL is like building a +house the traditional way: to add a window, you first need a frame; to have a +frame, you need a wall; and so on. + If your schema looks like this: .. code-block:: sdl diff --git a/docs/reference/ddl/index.rst b/docs/reference/ddl/index.rst deleted file mode 100644 index 2f6dde9b488..00000000000 --- a/docs/reference/ddl/index.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _ref_eql_ddl: - -DDL -=== - -:edb-alt-title: Data Definition Language - -EdgeQL includes a set of *data definition language* (DDL) commands that -manipulate the database's schema. DDL is the low-level equivalent to -:ref:`Gel schema definition language `. You can execute DDL -commands against your database, just like any other EdgeQL query. - -.. code-block:: edgeql-repl - - gel> create type Person { - .... create required property name -> str; - .... }; - OK: CREATE TYPE - gel> create type Movie { - .... create required property title -> str; - .... create required link director -> Person; - .... }; - OK: CREATE TYPE - -In DDL, the *order* of commands is important. In the example above, you -couldn't create ``Movie`` before ``Person``, because ``Movie`` contains a link -to ``Person``. - -Under the hood, all migrations are represented as DDL scripts: a sequence of -imperative commands representing the migration. When you :ref:`create a -migration ` with the CLI, Gel produces a DDL script. - - -Comparison to SDL ------------------ - -SDL is sort of like a 3D printer: you design the final shape and it puts -it together for you. DDL is like building a house with traditional -methods: to add a window, you first need a frame, to have a frame you -need a wall, and so on. - -DDL lets you make quick changes to your schema without creating migrations. But -it can be dangerous too; some ``DDL`` commands can destroy user data -permanantly. In practice, we recommend most users stick with SDL until they get -comfortable, then start experimenting with DDL. - diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 85b26488fa0..f7c57cb6ef1 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -13,7 +13,6 @@ Reference edgeql/index - ddl/index connection environment projects From f7bf3023d6ce4930e07c680b34a3eb324934c740 Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Wed, 19 Feb 2025 23:30:11 -0800 Subject: [PATCH 2/6] Refactor branches --- .../admin => datamodel}/branches.rst | 74 ++++++++++------ docs/datamodel/index.rst | 86 +++++++++---------- docs/datamodel/linkprops.rst | 2 +- docs/datamodel/properties.rst | 10 --- docs/intro/migrations.rst | 2 +- docs/reference/admin/index.rst | 1 - 6 files changed, 87 insertions(+), 88 deletions(-) rename docs/{reference/admin => datamodel}/branches.rst (65%) diff --git a/docs/reference/admin/branches.rst b/docs/datamodel/branches.rst similarity index 65% rename from docs/reference/admin/branches.rst rename to docs/datamodel/branches.rst index 0f3d85cd8bb..43d92397306 100644 --- a/docs/reference/admin/branches.rst +++ b/docs/datamodel/branches.rst @@ -1,20 +1,38 @@ +.. _ref_datamodel_branches: +.. _ref_datamodel_databases: + .. versionadded:: 5.0 -.. _ref_admin_branches: +======== +Branches +======== + +Gel's |branches| are equivalent to PostgreSQL's *databases* and map to +them directly. Gel comes with tooling to help manage branches and build +a development workflow around them. E.g. when developing locally you can +map your Gel branches to your Git branches, and when using Gel Cloud and +GitHub you can have a branch per PR. + -====== -Branch -====== +CLI commands +============ + +Refer to the :ref:`gel branch ` command group for +details on the CLI commands for managing branches. -:edb-alt-title: Branches +.. _ref_admin_branches: + +DDL commands +============ -This section describes the administrative commands pertaining to -:ref:`branches `. +These are low-level commands that are used to create, alter, and drop branches. +You can use them when experimenting in REPL, of if you want to create your own +tools to manage Gel branches. Create empty branch -=================== +------------------- :eql-statement: @@ -25,13 +43,13 @@ Create a new branch without schema or data. create empty branch ; Description ------------ +^^^^^^^^^^^ The command ``create empty branch`` creates a new Gel branch without schema or data, aside from standard schemas. -Examples --------- +Example +^^^^^^^ Create a new empty branch: @@ -41,24 +59,24 @@ Create a new empty branch: Create schema branch -==================== +-------------------- :eql-statement: -Create a new branch copying the schema of an existing branch. +Create a new branch copying the schema (without data)of an existing branch. .. eql:synopsis:: create schema branch from ; Description ------------ +^^^^^^^^^^^ The command ``create schema branch`` creates a new Gel branch with schema copied from an already existing branch. -Examples --------- +Example +^^^^^^^ Create a new schema branch: @@ -68,7 +86,7 @@ Create a new schema branch: Create data branch -================== +------------------ :eql-statement: @@ -79,13 +97,13 @@ Create a new branch copying the schema and data of an existing branch. create data branch from ; Description ------------ +^^^^^^^^^^^ The command ``create data branch`` creates a new Gel branch with schema and data copied from an already existing branch. -Examples --------- +Example +^^^^^^^ Create a new data branch: @@ -95,7 +113,7 @@ Create a new data branch: Drop branch -=========== +----------- :eql-statement: @@ -106,7 +124,7 @@ Remove a branch. drop branch ; Description ------------ +^^^^^^^^^^^ The command ``drop branch`` removes an existing branch. It cannot be executed while there are existing connections to the target branch. @@ -115,8 +133,8 @@ while there are existing connections to the target branch. Executing ``drop branch`` removes data permanently and cannot be undone. -Examples --------- +Example +^^^^^^^ Remove a branch: @@ -126,7 +144,7 @@ Remove a branch: Alter branch -============ +------------ :eql-statement: @@ -137,14 +155,14 @@ Rename a branch. alter branch rename to ; Description ------------ +^^^^^^^^^^^ The command ``alter branch … rename`` changes the name of an existing branch. It cannot be executed while there are existing connections to the target branch. -Examples --------- +Example +^^^^^^^ Rename a branch: diff --git a/docs/datamodel/index.rst b/docs/datamodel/index.rst index 0dc7824db4d..86f6dd0bcba 100644 --- a/docs/datamodel/index.rst +++ b/docs/datamodel/index.rst @@ -11,46 +11,53 @@ Schema :maxdepth: 3 :hidden: - primitives objects properties links computeds + primitives indexes constraints + inheritance aliases - annotations globals access_policies - modules functions triggers mutation_rewrites - inheritance linkprops - extensions + modules migrations + branches + extensions + annotations future comparison introspection/index -|Gel| schemas are declared using **SDL** (Gel's Schema Definition -Language). +|Gel| schema is a high-level description of your application's data model. +In the schema, you define your types, links, access policies, functions, +triggers, constraints, indexes, and more. + +Gel schema is strictly typed and is high-level enough to be mapped directly +to mainstream programming languages and back. + .. _ref_eql_sdl: Schema Definition Language --------------------------- +========================== -The database schema is defined inside |.gel| files with Gel Schema Definition -Language, or *SDL* for short. It's common to define the entire schema in -a single file called :dotgel:`default`, but you can split it across multiple -files if you wish. Since SDL is declarative in nature, the specific order of -declarations of module blocks, types, or schema files does not matter. +Migrations are sequences of *data definition language* (DDL) commands. +DDL is a low-level language that tells the database exactly how to change +the schema. You typically won't need to write any DDL by hand; the Gel server +will generate it for you. + +For a full guide on migrations, refer to the :ref:`Creating and applying +migrations ` guide or the +:ref:`migrations reference ` section. -By convention, your schema files should live in a directory called ``dbschema`` -in the root of your project. Example: @@ -77,7 +84,7 @@ Example: geldata/edgedb-vim>`_. Migrations and DDL ------------------- +================== Gel's baked-in migration system lets you painlessly evolve your schema over time. Just update the contents of your |.gel| file(s) and use the |Gel| CLI @@ -101,40 +108,25 @@ migrations ` guide or the .. _ref_datamodel_terminology: - -Terminology ------------ - .. _ref_datamodel_instances: -Instance -^^^^^^^^ - -A |Gel| **instance** is a running Gel process. Instances can be created, -started, stopped, and destroyed locally with the :ref:`Gel CLI -`. - -.. _ref_datamodel_databases: -.. _ref_datamodel_branches: - -Branch -^^^^^^ - -.. versionadded:: 5.0 - -Prior to |EdgeDB| 5 and Gel, *branches* were called "databases" -(and "databases" is what Gel branches map to in PostgreSQL). - -Instances can be branched when working on new features, similar to branches in -your VCS. Each branch has its own schema and data. +Instances, branches, and modules +================================ +Gel is like a stack of containers: -Module -^^^^^^ +* The *instance* is the running Gel process. Every instance has one or + more |branches|. Instances can be created, started, stopped, and + destroyed locally with :ref:`gel project ` + or low-level :ref:`gel instance ` commands. -Each |branch| has a schema consisting of several -**modules**, each with a unique name. Modules can be used to organize large -schemas into logical units. In practice, though, most users put their entire -schema inside a single module called ``default``. +* A *branch* is where your schema and data live. Branches map to PostgreSQL + databases. Like instances, branches can be conveniently created, removed, + and switched with the :ref:`gel branch ` commands. + Read more about branches in the + :ref:`branches reference `. -Read more about modules in the :ref:`modules ` section. +* A *module* is a collection of types, functions, and other definitions. + The default module is called ``default``. Modules are used to organize + your schema logically. Read more about modules in the + :ref:`modules reference `. diff --git a/docs/datamodel/linkprops.rst b/docs/datamodel/linkprops.rst index 6cb6213698f..da16f9403a4 100644 --- a/docs/datamodel/linkprops.rst +++ b/docs/datamodel/linkprops.rst @@ -4,7 +4,7 @@ Link properties =============== -:index: property, link property +.. index:: property, link property, linkprops, link table, relations, @ Links, like objects, can also contain **properties**. These are used to store metadata about the link. Due to how they're persisted under the hood, diff --git a/docs/datamodel/properties.rst b/docs/datamodel/properties.rst index 9c09dba2aad..64e5552d6ee 100644 --- a/docs/datamodel/properties.rst +++ b/docs/datamodel/properties.rst @@ -245,16 +245,6 @@ are declared independent of a source or target, can contain :ref:`annotations }; } - -Link properties -=============== - -.. index:: linkprops, relations, link table - -Properties can also be defined on **links**. For a full guide, refer to -:ref:`the dedicated page `. - - Overloading properties ====================== diff --git a/docs/intro/migrations.rst b/docs/intro/migrations.rst index d6df71f65ae..dc37a5e2680 100644 --- a/docs/intro/migrations.rst +++ b/docs/intro/migrations.rst @@ -4,7 +4,7 @@ Migrations ========== -:index: migrations fill_expr cast_expr +.. index:: migrations, fill_expr, cast_expr |Gel's| baked-in migration system lets you painlessly evolve your schema throughout the development process. If you want to work along with this guide, diff --git a/docs/reference/admin/index.rst b/docs/reference/admin/index.rst index 4eb523f216e..7770cf540dc 100644 --- a/docs/reference/admin/index.rst +++ b/docs/reference/admin/index.rst @@ -35,7 +35,6 @@ Administrative commands for managing Gel: :maxdepth: 3 :hidden: - branches configure databases roles From 002dd965a75c0f3f037ba8a4fd8e458e8babc6e0 Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Wed, 19 Feb 2025 23:48:43 -0800 Subject: [PATCH 3/6] Kill 'eql:section-intro-page', fix rest docs --- docs/changelog/index.rst | 1 - docs/cli/index.rst | 2 - docs/clients/graphql/index.rst | 2 - docs/clients/index.rst | 2 - docs/datamodel/index.rst | 1 - docs/edgeql/index.rst | 1 - docs/guides/contributing/documentation.rst | 79 ---------------------- docs/guides/index.rst | 2 - docs/intro/index.rst | 2 - docs/reference/index.rst | 1 - docs/stdlib/index.rst | 1 - 11 files changed, 94 deletions(-) diff --git a/docs/changelog/index.rst b/docs/changelog/index.rst index 8bc112918bb..6bafa1ec04f 100644 --- a/docs/changelog/index.rst +++ b/docs/changelog/index.rst @@ -1,4 +1,3 @@ -.. eql:section-intro-page:: changelog ========= Changelog diff --git a/docs/cli/index.rst b/docs/cli/index.rst index 5749776e08d..c70b9f28d8d 100644 --- a/docs/cli/index.rst +++ b/docs/cli/index.rst @@ -1,5 +1,3 @@ -.. eql:section-intro-page:: cli - .. _ref_cli_overview: === diff --git a/docs/clients/graphql/index.rst b/docs/clients/graphql/index.rst index 0297f4c89b3..3bfbf2f07dd 100644 --- a/docs/clients/graphql/index.rst +++ b/docs/clients/graphql/index.rst @@ -1,5 +1,3 @@ -.. eql:section-intro-page:: graphql - .. _ref_graphql_index: ======= diff --git a/docs/clients/index.rst b/docs/clients/index.rst index 575fae31270..3c82bcc09bf 100644 --- a/docs/clients/index.rst +++ b/docs/clients/index.rst @@ -1,5 +1,3 @@ -.. eql:section-intro-page:: clients - .. _ref_clients_index: ================ diff --git a/docs/datamodel/index.rst b/docs/datamodel/index.rst index 86f6dd0bcba..1ff102eb5f4 100644 --- a/docs/datamodel/index.rst +++ b/docs/datamodel/index.rst @@ -1,4 +1,3 @@ -.. eql:section-intro-page:: datamodel .. versioned-section:: .. _ref_datamodel_index: diff --git a/docs/edgeql/index.rst b/docs/edgeql/index.rst index 02047a150dd..f82aaed9614 100644 --- a/docs/edgeql/index.rst +++ b/docs/edgeql/index.rst @@ -1,4 +1,3 @@ -.. eql:section-intro-page:: edgeql .. versioned-section:: .. _ref_edgeql: diff --git a/docs/guides/contributing/documentation.rst b/docs/guides/contributing/documentation.rst index 9706686f3ee..b5bfba0d10f 100644 --- a/docs/guides/contributing/documentation.rst +++ b/docs/guides/contributing/documentation.rst @@ -44,10 +44,6 @@ Guidelines Style ===== -- **Lines should be no longer than 79 characters.** This is enforced by linters - as part of our CI process. Linting :ref:`can be disabled - `, but this should not be - used unless it's necessary and only for as long as it is necessary. - **Remove trailing whitespace or whitespace on empty lines.** - **Surround references to parameter named with asterisks.** You may be tempted to surround parameter names with double backticks (````param````). We avoid @@ -79,12 +75,6 @@ Most of our documentation (including this guide) lives in `the geldata repository `_ in `the docs directory `_. -Documentation for some of our client libraries lives inside the client's repo. -If you don't find it in the geldata repo at ``docs/clients``, you'll probably -find it alongside the client itself. These clients will also have documentation -stubs inside the geldata repository directing you to the documentation's -location. - How to Build It =============== @@ -1023,9 +1013,6 @@ Use the ``versionchanged`` directive to mark content related to a change in existing functionality across |Gel| versions. Provide the applicable version as an argument by placing it just after the directive on the same line. -Unlike ``versionadded``, ``versionchanged`` is always used with content to show -or hide that content based on the user's selection in the version dropdown. - **Example** .. lint-off @@ -1060,45 +1047,6 @@ or hide that content based on the user's selection in the version dropdown. Other Useful Tricks =================== -.. _ref_guide_contributing_documentation_linter_toggle: - -Temporarily Disabling Linting ------------------------------ - -``.. lint-off`` and ``.. lint-on`` toggle linting off or on. In general, -linting should stay on except in cases where it's impossible to keep it on. -This might be when code or a URL must exceed the maximum line length of 79 -characters. - -You would typically use this by toggling linting off with ``.. lint-off`` just -before the offending block and back on with ``.. lint-on`` after the block. - -**Example** - -.. lint-off - -.. code-block:: - - .. lint-off - - .. code-block:: - - GET http://localhost:/branch/main/edgeql?query=insert%20Person%20%7B%20name%20%3A%3D%20%3Cstr%3E$name%20%7D%3B&variables=%7B%22name%22%3A%20%22Pat%22%7D - - .. lint-on - -.. lint-on - -.. note:: - - This is actually a comment our linter pays attention to rather than a - directive. As a result, it does not end with a colon (``:``) like a - directive would. - -.. note:: - - This does not render any visible output. - Embedding a YouTube Video ------------------------- @@ -1108,30 +1056,3 @@ Embed only videos from `the Gel YouTube channel .. code-block:: .. edb:youtube-embed:: OZ_UURzDkow - - -Displaying Illustrations ------------------------- - -Using the ``.. eql:section-intro-page::`` directive, you can display one of -several illustrations. Pass the name of the illustration to the directive by -placing it after the directive on the same line. - -**Example** - -.. code-block:: - - .. eql:section-intro-page:: edgeql - -**Rendered** - -.. eql:section-intro-page:: edgeql - -.. lint-off - -See `the list of illustration names -`_ -and `view the images they map to -`_. - -.. lint-on diff --git a/docs/guides/index.rst b/docs/guides/index.rst index 402d109d121..7d0b1da2186 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -1,5 +1,3 @@ -.. eql:section-intro-page:: guides - .. _ref_guides: ====== diff --git a/docs/intro/index.rst b/docs/intro/index.rst index f07e30fe31c..1a2bf8edcb2 100644 --- a/docs/intro/index.rst +++ b/docs/intro/index.rst @@ -1,5 +1,3 @@ -.. eql:section-intro-page:: introduction - .. _ref_intro: Get Started diff --git a/docs/reference/index.rst b/docs/reference/index.rst index f7c57cb6ef1..a137603f8b6 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,4 +1,3 @@ -.. eql:section-intro-page:: reference .. versioned-section:: .. _ref_reference_index: diff --git a/docs/stdlib/index.rst b/docs/stdlib/index.rst index ecede42cdec..504870a6fe7 100644 --- a/docs/stdlib/index.rst +++ b/docs/stdlib/index.rst @@ -1,4 +1,3 @@ -.. eql:section-intro-page:: stdlib .. versioned-section:: .. _ref_std: From 08e5275a51285d7d8be4d4463938eaa86df4d147 Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Thu, 20 Feb 2025 00:05:57 -0800 Subject: [PATCH 4/6] Document ReST substitutions --- docs/guides/contributing/documentation.rst | 88 ++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/docs/guides/contributing/documentation.rst b/docs/guides/contributing/documentation.rst index b5bfba0d10f..ec426c330bd 100644 --- a/docs/guides/contributing/documentation.rst +++ b/docs/guides/contributing/documentation.rst @@ -870,6 +870,31 @@ renders as :eql:kw:`the "detached" keyword `. Documenting the EdgeQL CLI ========================== +"gelcmd" role +------------- + +.. lint-off + +Use ``:gelcmd:`` role to document or refer to CLI commands, use ``|gelcmd|`` to +render just ``gel`` in the text. + +.. lint-on + +**Example** + +.. code-block:: + + Use |gelcmd| to cook yourself a delicious meal. Use :gelcmd:`eat` to + eat it. + +**Rendered** + +Use |gelcmd| to cook yourself a delicious meal. Use :gelcmd:`eat` to +eat it. + +cli:synopsis +------------ + Document a CLI command using the ``cli:synopsis`` directive like this: **Example** @@ -905,6 +930,69 @@ You can then document arguments and options using the ``:cli:synopsis:`` role. The name of the file to backup the database into. +Substitutions +============= + +There's a few substitutions and ReST toles that are useful when documenting +certain terms and concepts: + +.. lint-off + +.. list-table:: + + * - **ReST markup** + - **Description** + + * - ``|gelcmd|`` and ``:gelcmd:`blah``` + - Renders to ``$ gel`` and ``$ gel blah``, with a context + tooltip explaining that the CLI command used to be called ``edgedb``. + + * - ``|geluri|`` and ``:geluri:`u:p@h:p/b``` + - Renders to ``gel://`` and ``gel://u:p@h:p/b``, + with a context tooltip explaining that the URI used to be ``edgedb://``. + + * - ``|Gel|`` and ``|Gel's|`` + - Renders to "Gel" and "Gel's", with a context tooltip explaining that + the Gel used to be called "EdgeDB". + + * - ``|branch|`` and ``|branches|`` + - Renders to "branch" and "branches", with a context tooltip explaining + that the term used to be called "database" in EdgeDB < 5. + + * - ``|EdgeDB|`` + - Renders to "EdgeDB", with a context tooltip explaining that + EdgeDB was renamed to Gel. + + * - ``|.gel|`` + - Renders to ``.gel``, with a context tooltip explaining that the file + extension used to be ``.esdl``. + + * - ``:dotgel:`foo``` + - Renders to ``foo.gel``, with a context tooltip explaining that the file + extension used to be ``.esdl``. + + * - ``:gelenv:`BLAH``` + - Renders to ``GEL_BLAH``, with a context tooltip explaining that this + environment variable used to be ``EDGEDB_BLAH``. + + * - ``|gel.toml|`` + - Renders to ``gel.toml``, with a context tooltip explaining that this + file used to be called ``edgedb.toml``. + + * - ``|gel-server|`` + - Renders to ``$ gel-server``, with a context tooltip explaining that + this command used to be called ``edgedb-server``. + + * - ``|admin|`` + - Renders to ``admin``, with a context tooltip explaining that this + username used to be called ``edgedb``. + + * - ``|main|`` + - Renders to ``main``, with a context tooltip explaining that this + branch used to be called ``edgedb``. + +.. lint-on + Documentation Versioning ======================== From 1dfdafc8337afef533413c77795a86047093cc7a Mon Sep 17 00:00:00 2001 From: James Clarke Date: Thu, 20 Feb 2025 17:43:14 +0000 Subject: [PATCH 5/6] 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 From 02c6d9fe2f995d9077b53fc0a2469808af599b4f Mon Sep 17 00:00:00 2001 From: Scott Trinh Date: Thu, 20 Feb 2025 14:13:04 -0500 Subject: [PATCH 6/6] cqa: Fix trailing whitespace --- docs/cloud/index.rst | 15 +++++++-------- docs/index.rst | 1 - docs/reference-intro.rst | 5 ++--- 3 files changed, 9 insertions(+), 12 deletions(-) diff --git a/docs/cloud/index.rst b/docs/cloud/index.rst index ed476153647..29c2d411a23 100644 --- a/docs/cloud/index.rst +++ b/docs/cloud/index.rst @@ -20,16 +20,16 @@ Cloud 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 ` @@ -37,8 +37,7 @@ Try a guide for connecting your app running on your platform of choice: * :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 @@ -46,7 +45,7 @@ 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 @@ -90,7 +89,7 @@ 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 ========================= @@ -159,4 +158,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. \ No newline at end of file + which will be useful to include with your ticket. diff --git a/docs/index.rst b/docs/index.rst index 510ad9c072e..0bf36f7af8d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,6 +26,5 @@ Welcome to the |Gel| |version| documentation. cheatsheets/index changelog/index cloud/index - reference-intro resources-intro diff --git a/docs/reference-intro.rst b/docs/reference-intro.rst index 40a9f852f7c..25a9fe1f174 100644 --- a/docs/reference-intro.rst +++ b/docs/reference-intro.rst @@ -27,12 +27,11 @@ Schema 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 ------ @@ -146,4 +145,4 @@ Admin ^^^^^ * :ref:`CLI ` * :ref:`REPL ` -* :ref:`Admin ` \ No newline at end of file +* :ref:`Admin `