Writing Gel Documentation​

geldata/gel​

The geldata repository contains all of its documentation in the docs/ directory. Run make docs to build the documentation in the geldata repo. The repository contains a Makefile for all of Sphinx's necessary build options. The documentation will be built to docs/build.

To run tests, first build Gel locally. Then run edb test -k doc.

Building the docs from this repo will not give you a high-fidelity representation of what users will see on the web site. For that, you may want to do a full documentation build.

Full Documentation Build​

A full documentation build requires more setup, but it is the only way to see your documentation exactly as the user will see it. This is not required, but it can be useful to help us review and approve your request more quickly by avoiding mistakes that would be easier to spot when they are fully rendered.

To build, clone our website repository and follow the installation instructions. Then run yarn dev to start a development server which also triggers a build of all the documentation.

reStructuredText Basics​

==========
Page Title
==========

Section
=======

Sub-Section
-----------

Sub-Sub-Section
^^^^^^^^^^^^^^^

.. rubric:: Yet Another Heading

*italicized*

**Bold**

.. _ref_eql_select_objects:

:ref:`ref_eql_select_objects`

:ref:`our documentation on selecting objects <ref_eql_select_objects>`

.. note::

    This paragraph is a note.

.. warning::

    This paragraph is a warning.

.. note:: A Note

    This paragraph is a note.

.. include:: ../stdlib/constraint_table.rst

.. list-table::

    * - Arrays
      - ``array<str>``
    * - Tuples (unnamed)
      - ``tuple<str, int64, bool>``
    * - Tuples (named)
      - ``tuple<name: str, age: int64, is_awesome: bool>``
    * - Ranges
      - ``range<float64>``

.. list-table::
    :class: seealso

    * - **See also**
    * - :ref:`Schema > Access policies <ref_datamodel_access_policies>`
    * - :ref:`SDL > Access policies <ref_eql_sdl_access_policies>`

====================================== =============================
Syntax                                 Inferred type
====================================== =============================
:eql:code:`select 3;`                  :eql:type:`int64`
:eql:code:`select 3.14;`               :eql:type:`float64`
:eql:code:`select 314e-2;`             :eql:type:`float64`
:eql:code:`select 42n;`                :eql:type:`bigint`
:eql:code:`select 42.0n;`              :eql:type:`decimal`
:eql:code:`select 42e+100n;`           :eql:type:`decimal`
====================================== =============================

Sphinx Basics​

.. toctree::
    :maxdepth: 3
    :hidden:

    code
    documentation

Inline Code​

Render inline code by surrounding it with double backticks:

Example

With the help of a ``with`` block, we can add filters, ordering, and
pagination clauses.

Rendered

With the help of a with block, we can add filters, ordering, and pagination clauses.

Code Blocks​

.. code-block:: [<language>]

    <code goes here>

Render a block of code. You can optionally provide a language argument. Below are the most common languages used in our docs:

• bash- Include the prompt and optionally the output. When a user clicks the "copy" button to copy the code, it will copy only the input without the prompt and output.

  Example

  .. code-block:: bash
  
      $ gel configure set listen_addresses 127.0.0.1 ::1

  Rendered

  Copy

  $ 

  gel configure set listen_addresses 127.0.0.1 ::1

• edgeql- Used for queries.

  Example

  .. code-block:: edgeql
  
      select BlogPost filter .id = <uuid>$blog_id;

  Rendered

  Copy

  select BlogPost filter .id = <uuid>$blog_id;

• edgeql-repl- An alternative to vanilla edgeql. Include the prompt and optionally the output. When a user clicks the "copy" button to copy the code, it will copy only the input without the prompt and output.

  Example

  .. code-block:: edgeql-repl
  
      db> insert Person { name := <str>$name };
      Parameter <str>$name: Pat
      {default::Person {id: e9009b00-8d4e-11ed-a556-c7b5bdd6cf7a}}

  Rendered

  Copy

  db> 

  insert Person { name := <str>$name };

  Parameter <str>$name: Pat
  {default::Person {id: e9009b00-8d4e-11ed-a556-c7b5bdd6cf7a}}

• go

• javascript

• python

  Example

  .. code-block:: javascript
  
      await client.query("select 'I ❤️ ' ++ <str>$name ++ '!';", {
        name: "rock and roll"
      });

  Rendered

  Copy

  await client.query("select 'I ❤️ ' ++ <str>$name ++ '!';", {
    name: "rock and roll"
  });

• sdl- Used for defining schema.

  Example

  .. code-block:: sdl
  
      module default {
        type Person {
          required property name -> str { constraint exclusive };
        }
      }

  Rendered

  Copy

  module default {
    type Person {
      required property name -> str { constraint exclusive };
    }
  }

• <language>-diff- Shows changes in a code block. Each line of code in these blocks must be prefixed by a character: + for an added line, - for a removed line, or an empty space for an unchanged line.

  Example

  .. code-block:: sdl-diff
  
          type Movie {
      -     property title -> str;
      +     required property title -> str;
            multi link actors -> Person;
          }

  Rendered

  Copy

    type Movie {
      property title -> str;
      required property title -> str;
      multi link actors -> Person;
    }
  

• No language- Formats the text as a code block but without syntax highlighting. Use this for syntaxes that do not offer highlighting or in cases where highlighting is unnecessary.

  Example

  .. code-block::
  
      [
        {"id": "ea7bad4c-35d6-11ec-9519-0361f8abd380"},
        {"id": "6ddbb04a-3c23-11ec-b81f-7b7516f2a868"},
        {"id": "b233ca98-3c23-11ec-b81f-6ba8c4f0084e"},
      ]

  Rendered

  [
    {"id": "ea7bad4c-35d6-11ec-9519-0361f8abd380"},
    {"id": "6ddbb04a-3c23-11ec-b81f-7b7516f2a868"},
    {"id": "b233ca98-3c23-11ec-b81f-6ba8c4f0084e"},
  ]

  Code blocks without a language specified do not have a "copy" button.

Code Tabs​

.. tabs::

Tabs are used to present code examples in multiple languages. This can be useful when you want to show a query in, for example, both EdgeQL and the TypeScript query builder.

Example

.. tabs::

    .. code-tab:: edgeql

        insert Movie {
          title := 'Doctor Strange 2',
          release_year := 2022
        };

    .. code-tab:: typescript

        const query = e.insert(e.Movie, {
          title: 'Doctor Strange 2',
          release_year: 2022
        });

        const result = await query.run(client);

Rendered

insert Movie {
  title := 'Doctor Strange 2',
  release_year := 2022
};

const query = e.insert(e.Movie, {
  title: 'Doctor Strange 2',
  release_year: 2022
});

const result = await query.run(client);

Functions​

To document a function use a .. eql:function:: directive. Include these elements:

• Specify the full function signature with a fully qualified name on the same line as the directive.

• Add a description of each parameter using :param $<name>: description:. $<name> must match the the name of the parameter in function's signature. If a parameter is positional rather than named, its number should be used instead (e.g. $1).

• Add a type for each parameter using :paramtype $<name>: <type>. For example: :paramtype $<name>: int64 declares that the type of the $<name> parameter is int64. If a parameter has more than one valid type, list them separated by "or" like this: :paramtype $<name>: int64 or str.

• Document the return value of the function with :return: and :returntype:. :return: marks a description of the return value and :returntype: its type.

• Finish with a few descriptive paragraphs and code samples. The first paragraph must be a single sentence no longer than 79 characters describing the function.

Example

.. eql:function:: std::array_agg(set of any, $a: any) -> array<any>

    :param $1: input set
    :paramtype $1: set of any

    :param $a: description of this param
    :paramtype $a: int64 or str

    :return: array made of input set elements
    :returntype: array<any>

    Return the array made from all of the input set elements.

    The ordering of the input set will be preserved if specified.

You can link to a function's documentation by using the :eql:func: role. For instance:

• :eql:func:`array_agg`;

• :eql:func:`std::array_agg`;

These will link to a function using the function's name as you have written in between the backticks followed by parentheses. Here are the above links rendered:

• array_agg();

• std::array_agg();

You can customize a link's label with this syntax: :eql:func:`aggregate a set as an array <array_agg>`. Here's the rendered output: aggregate a set as an array

Operators​

Use the .. eql:operator:: directive to document an operator. On the same line as the directive, provide a string argument of the format <operator-id>: <operator-signature>

Add a :optype <operand-name>: <type> field for each of the operator signature's operands to declare their types.

Example

.. eql:operator:: PLUS: A + B

    :optype A: int64 or str or bytes
    :optype B: any
    :resulttype: any

    Arithmetic addition.

You can link to an operator's documentation by using the :eql:op: role, followed by the operator's ID you specified in your argument to .. eql:operator::. For instance: :eql:op:`plus` which renders as plus. You can customize the link label like this: :eql:op:`+ <plus>`, which renders as +.

Statements​

Use the :eql-statement: field to sections that describe a statement. Add the :eql-haswith: field if the statement supports a with block.

Select
======

:eql-statement:
:eql-haswith:

``select``--retrieve or compute a set of values.

.. eql:synopsis::

    [ with <with-item> [, ...] ]

    select <expr>

    [ filter <filter-expr> ]

    [ order by <order-expr> [direction] [then ...] ]

    [ offset <offset-expr> ]

    [ limit  <limit-expr> ] ;

After laying out the formal syntax, describe the function of each clause with a synopsis like this:

:eql:synopsis:`filter <filter-expr>`
    The optional ``filter`` clause, where :eql:synopsis:`<filter-expr>`
    is any expression that has a result of type :eql:type:`bool`.
    The condition is evaluated for every element in the set produced by
    the ``select`` clause.  The result of the evaluation of the
    ``filter`` clause is a set of boolean values.  If at least one value
    in this set is ``true``, the input element is included, otherwise
    it is eliminated from the output.

These descriptions can each contain as many paragraphs as needed to adequately describe the clause. Follow the format used in the PostgreSQL documentation. See the PostgreSQL SELECT statement reference page for an example.

Use :eql:stmt:`select` to link to the statement's documentation. When rendered the link looks like this: select. Customize the label with :eql:stmt:`the select statement <select>` which renders as this: the select statement.

Types​

To document a type, use the .. eql:type:: directive. Follow the directive with the fully-qualified name of the type on the same line. The block should contain the type's description.

.. eql:type:: std::bytes

    A sequence of bytes.

To link to a type's documentation, use :eql:type:`bytes` which renders as bytes. You may use the fully qualified name in your reference — :eql:type:`std::bytes` — which renders as std::bytes. Both forms reference the same location in the documentation. Link labels can be customized with :eql:type:`the bytes type <bytes>` which renders like this: the bytes type.

Keywords​

Document a keyword using the .. eql:keyword:: directive.

.. eql:keyword:: with

    The ``with`` block in EdgeQL is used to define aliases.

If a keyword is compound use a hyphen between each word.

.. eql:keyword:: set-of

To link to a keyword's documentation, use the :eql:kw: role like this: :eql:kw:`detached` which renders as detached. You can customize the link label like this: :eql:kw:`the "detached" keyword <detached>` which renders as the "detached" keyword.

"gelcmd" role​

Use :gelcmd: role to document or refer to CLI commands, use |gelcmd| to render just gel in the text.

Example

Use |gelcmd| to cook yourself a delicious meal. Use :gelcmd:`eat` to
eat it.

Rendered

Use gel to cook yourself a delicious meal. Use gel eat to eat it.

cli:synopsis​

Document a CLI command using the cli:synopsis directive like this:

Example

.. cli:synopsis::

    gel dump [<options>] <path>

Rendered

gel dump [options] path

The synopsis should follow the format used in the PostgreSQL documentation. See the PostgreSQL SELECT statement reference page for an example.

You can then document arguments and options using the :cli:synopsis: role.

Example

:cli:synopsis:`<path>`
    The name of the file to backup the database into.

Rendered

path

The name of the file to backup the database into.

New in Version​

Content addressing anything new in a given version are marked with the versionadded directive. Provide the applicable version as an argument by placing it just after the directive on the same line.

The directive behaves differently depending on the context.

• When the directive has content (i.e., an indented paragraphs below the directive), that content will be shown or hidden based on the version switch.

• When the directive is placed immediately after a section header or inside a description block for a function, type, operator, statement, or keyword, that entire section or block is marked to be shown or hidden based on the version selected.

• When the directive is placed on the top line of any page before any content or reStructuredText labels (e.g., .. _ref_eql_select:), it applies to the entire page.

Example with Content

.. versionadded:: 7.0

    This is a new feature that was added in Gel 7.0.

Rendered

Section Example

Source deletion
^^^^^^^^^^^^^^^

.. versionadded:: 7.0

Source deletion policies determine what action should be taken when the
*source* of a given link is deleted. They are declared with the ``on source
delete`` clause.
...

Rendered

See the "Source deletion" section of the "Links" documentation for a rendered section example of .. versionadded:: 2.0.

Description Block Example

.. eql:type:: cal::date_duration

    A type for representing a span of time in days.

Rendered

See cal::date_duration for a rendered description block example of .. versionadded:: 2.0.

Full-Page Example

.. versionadded:: 2.0

.. _ref_datamodel_globals:

=======
Globals
=======
...

Rendered

See the "Globals" documentation page for a full-page example of .. versionadded:: 2.0.

Changed in Version​

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.

Example

.. versionchanged:: 8.0

    Starting with the upcoming Gel 8.0, access policy restrictions will
    **not** apply to any access policy expression. This means that when
    reasoning about access policies it is no longer necessary to take other
    policies into account. Instead, all data is visible for the purpose of
    *defining* an access policy.

Rendered

Embedding a YouTube Video​

Embed only videos from the Gel YouTube channel

.. edb:youtube-embed:: OZ_UURzDkow