From 4c8ab19c0cfd41f5b8016347cc271b2ab26caeb2 Mon Sep 17 00:00:00 2001 From: Dhghomon Date: Tue, 30 Jan 2024 02:12:08 +0900 Subject: [PATCH] Add content + rephrase --- docs/ui/auth_admin.rst | 4 ++-- docs/ui/client_settings.rst | 10 +++++----- docs/ui/data_explorer.rst | 14 +++++++------- docs/ui/database_dashboard.rst | 8 ++++---- docs/ui/editor.rst | 19 +++++++++---------- docs/ui/index.rst | 8 ++++---- docs/ui/schema_viewer.rst | 10 +++++++--- docs/ui/ui_home.rst | 7 ++++--- docs/ui/ui_repl.rst | 20 ++++++++++++++++++++ 9 files changed, 62 insertions(+), 38 deletions(-) diff --git a/docs/ui/auth_admin.rst b/docs/ui/auth_admin.rst index efb0be4664d..3711654204e 100644 --- a/docs/ui/auth_admin.rst +++ b/docs/ui/auth_admin.rst @@ -4,9 +4,9 @@ Auth Admin ========== -The Auth page inside the EdgeDB is used to set up authentication for +The auth page inside the EdgeDB UI allows you to set up authentication for your app built into the EdgeDB server. The details for setting up auth -admin via are in their own guide :ref:`here `. +admin are in their own guide :ref:`here `. .. image:: ../guides/auth/images/ui-auth.png :alt: The EdgeDB local development server UI highlighting the auth admin diff --git a/docs/ui/client_settings.rst b/docs/ui/client_settings.rst index 87011ec6fe5..cc433dd7e6b 100644 --- a/docs/ui/client_settings.rst +++ b/docs/ui/client_settings.rst @@ -9,9 +9,9 @@ Client settings :width: 100% The UI exposes a number of :ref:`configuration parameters ` -in a dropdown bar at the top of all database dashboard screens when the -Client Settings button is clicked. They can be modified by double -clicking on the bar. +in a dropdown bar at the top of all database dashboard screens. Clicking +on the Client Settings button will show the bar, after which a double +click allows you to modify them. The parameters are as follows: @@ -24,8 +24,8 @@ Globals Config ------ -- ``allow_bare_ddl``: Whether DDL is allowed to be used outside the normal - migration flow. Default: ``NeverAllow``, can be set to ``AlwaysAllow``. +- ``allow_bare_ddl``: Whether DDL may be used outside the normal migration + flow. Default: ``NeverAllow``, can be set to ``AlwaysAllow``. Note: This parameter accepts enum values, not booleans. - ``allow_user_specified_id``: Whether users are allowed to manually set the 'id' property. Default: ``false``. diff --git a/docs/ui/data_explorer.rst b/docs/ui/data_explorer.rst index 8fb4f2e4b14..e14900efa90 100644 --- a/docs/ui/data_explorer.rst +++ b/docs/ui/data_explorer.rst @@ -5,7 +5,7 @@ Data Explorer ============= .. image:: images/data_explorer.png - :alt: The Data Explorer page in the EdgeDB UI. The icon is three bars + :alt: The data explorer page in the EdgeDB UI. The icon is three bars stacked on top of each other: blue, purple, and orange. A sample query via the Data Explorer shows information about a user-defined object type called a Booking. @@ -17,9 +17,9 @@ which by nature must be specified manually). Instead, the data explorer gives point-and-click access to the database's objects, including inserting new objects and modifying existing ones. -This makes the data explorer the ideal solution for any users of an EdgeDB -database who lack a technical background or the time needed to learn -the ins and outs of a new database. It is also useful for skilled users -who are looking to explore the links between multiple object types in -possible multiple levels of depth without having to continually modify a -query to do so. \ No newline at end of file +This makes the data explorer the ideal solution for EdgeDB users without +a technical background or new users lacking the time needed to learn the +ins and outs of a new database. It is also useful for skilled users +who are looking to explore the links between object types over possible +multiple levels of depth without having to continually recreate queries +to do so. \ No newline at end of file diff --git a/docs/ui/database_dashboard.rst b/docs/ui/database_dashboard.rst index b94a83b3abe..bcb51ce4f64 100644 --- a/docs/ui/database_dashboard.rst +++ b/docs/ui/database_dashboard.rst @@ -5,9 +5,9 @@ Dashboard ========= .. image:: images/database_dashboard.png - :alt: The Database Dashboard page in the EdgeDB UI. Large green buttons - give access to other pages such as the REPL, Editor, and - Schema Viewer. The total number of objects and object types in + :alt: The database dashboard page in the EdgeDB UI. Large green buttons + give access to other pages such as the REPL, editor, and + schema viewer. The total number of objects and object types in the database are displayed below, along with links to parts of the EdgeDB website such as the Quickstart, Tutorial, and Easy EdgeDB book. @@ -17,6 +17,6 @@ The dashboard for each database displays the number of object types and total number of objects contained within. Besides this, the dashboard is simply a minimal set of buttons leading to the -other parts of the UI (the REPL, Editor, Schema Viewer, and Data Viewer) +other parts of the UI (the REPL, editor, schema viewer, and data viewer), and some parts of the EdgeDB documentation that a new user will find most useful. \ No newline at end of file diff --git a/docs/ui/editor.rst b/docs/ui/editor.rst index 2aa58067a03..8907df7c1e8 100644 --- a/docs/ui/editor.rst +++ b/docs/ui/editor.rst @@ -5,7 +5,7 @@ Editor ====== .. image:: images/editor.png - :alt: The Editor page in the EdgeDB UI, inside which the Query Builder + :alt: The editor page in the EdgeDB UI, inside which the query builder is shown as the user puts together a query to see the name property for a user-defined type called Book. A filter on the object's id and a limit to the number of object types returned are being set. @@ -17,24 +17,23 @@ Query Editor ------------ .. image:: images/editor.png - :alt: The Editor tab in the EdgeDB UI Editor page, showing a query + :alt: The Editor tab in the EdgeDB UI editor page, showing a query appended with the analyze keyword to analyze performance. The performance results show up in a graph on the right, with separate colored rectangles for each link traversed by the query. :width: 100% -The Query Editor is outwardly similar to the REPL besides some -auto-completion, but is most useful when paired with the ``analyze`` -keyword. Prepending ``analyze`` to the front of any query will -display a visual query analyzer to help you tweak performance on your -EdgeQL queries. +The query editor outwardly resembles the REPL with some auto-completion +functionality, but is most useful when paired with the ``analyze`` keyword. +Prepending ``analyze`` to the front of any query will display a visual +analyzer to help you tweak the performance of your EdgeQL queries. Query Builder ------------- -The Query Builder is by far the easiest way for new users to EdgeDB to +The query builder is by far the easiest way for new users to EdgeDB to put together a ``select`` query, and the second easiest part of the UI -to use after the Data Explorer. The Query Builder is an entirely +to use after the data explorer. The query builder is an entirely point-and-click interface that walks you through the steps of a ``select`` query, including selecting properties and links inside an object, ``filter``, ``order by``, and setting an ``offset`` and ``limit`` @@ -44,4 +43,4 @@ History ------- The History button inside the Editor tab pulls up the most recently used -queries for both the Query Editor and Query Builder. \ No newline at end of file +queries for both the query editor and query builder. \ No newline at end of file diff --git a/docs/ui/index.rst b/docs/ui/index.rst index 3440cc96858..8c99313a749 100644 --- a/docs/ui/index.rst +++ b/docs/ui/index.rst @@ -5,7 +5,7 @@ UI == EdgeDB UI is a beautiful, feature-rich admin panel baked directly into all -EdgeDB 2.0+ instances. +EdgeDB instances. The UI automatically opens in your default browser on a ``localhost`` page via a single command: @@ -34,12 +34,12 @@ or set the ``EDGEDB_SERVER_ADMIN_UI`` :ref:`environment variable ` to ``enabled``. The UI has three similar pages that each allow users to query the database: -the REPL, the Editor, and the Data Explorer. +the REPL, the editor, and the data explorer. Outright new users to EdgeDB who need to query or work with objects in a -database will find the Data Explorer tab the easiest to use, as it allows +database will find the data explorer tab the easiest to use, as it allows simple point-and-click access to objects without using any EdgeQL. The next -easiest page to use is the Query Builder inside the Editor tab, which does +easiest page to use is the query builder inside the Editor tab, which does use EdgeQL but is also point-and-click as it walks users through every step of a query. The REPL is the most advanced tab in the UI as it requires the user to be able to compose queries in EdgeQL. diff --git a/docs/ui/schema_viewer.rst b/docs/ui/schema_viewer.rst index cb9863bf260..3aa8d5c5b1d 100644 --- a/docs/ui/schema_viewer.rst +++ b/docs/ui/schema_viewer.rst @@ -60,6 +60,10 @@ For example, a search for 'max val' immediately shows the following output: Graph view ---------- -- Types are shown as boxes with -- Links are shown as arrows from one type to another, with any link - properties shown tucked inside the arrow. \ No newline at end of file +- Object types are shown as either blue boxes for concrete types, or gray + boxes for abstract types. Object types that extend another object type + will show this via a gray arrow. +- Links show up as purple arrows from one type to another, with any link + properties shown tucked inside the arrow. +- Zooming in and out along with dragging and dropping boxes allow you to + visually interact with your schema. \ No newline at end of file diff --git a/docs/ui/ui_home.rst b/docs/ui/ui_home.rst index c03c8a51e8e..78b7fba6384 100644 --- a/docs/ui/ui_home.rst +++ b/docs/ui/ui_home.rst @@ -12,7 +12,7 @@ UI Home new database. :width: 100% -The UI homepage displays one button per database inside the instance. +The UI homepage displays one button per database inside an instance. New instances will contain a database called ``edgedb`` by default. A new database can be added to the current instance by clicking on @@ -24,11 +24,12 @@ those new to EdgeDB. Clicking on this will create a database called EdgeDB tutorial. As such, the quickest way for newcomers to EdgeDB to start interacting with -a working database via the UI in EdgeDB is by doing the following: +a working database with populated objects in the UI can be done in just +three steps: - ``edgedb project init`` on the command line to start an instance, - ``edgedb ui`` on the command line to open the UI, - Clicking on ``Create example database`` to create the example database. Clicking on any of the databases on the UI homepage will take you to its -dashboard. \ No newline at end of file +own dashboard. \ No newline at end of file diff --git a/docs/ui/ui_repl.rst b/docs/ui/ui_repl.rst index e3d2790938a..7f3b0c6a245 100644 --- a/docs/ui/ui_repl.rst +++ b/docs/ui/ui_repl.rst @@ -23,6 +23,26 @@ Some behavior differs from that of the CLI REPL: has its own ``\retro`` slash command to change the UI layout to a 1980s classic green-on-black feel!) +Shortcuts +--------- + +- ``Ctrl+Enter``: Run query +- ``Ctrl+ArrowUp/ArrowDown``: Navigate query history + +Backslash commands +------------------ + +- ``\l``, or ``\list databases``: List databases +- ``\ls``, or ``\list scalars``: List scalar types +- ``\lt``, or ``\list types``: List scalar types +- ``\lr``, or ``\list roles``: List roles +- ``\lm``, or ``\list modules``: List modules +- ``\la``, or ``\list aliases``: List expression aliases +- ``\lc``, or ``\list casts``: List casts +- ``\li``, or ``\list indexes``: List indexes +- ``\c DBNAME``, or ``\connect DBNAME``: Connect to database DBNAME +- ``\?``, ``\h``, or ``\help``: Show help on backslash commands + .. lint-off .. _slash_command: https://github.com/edgedb/edgedb-ui/blob/e1b63d9395d8ea8cfac4069811f9d6ffb0bf8a8d/shared/studio/tabs/repl/state/commands.ts#L31