diff --git a/docs/cli/edgedb_branch/edgedb_branch_merge.rst b/docs/cli/edgedb_branch/edgedb_branch_merge.rst index 374520be65f..52044f053e2 100644 --- a/docs/cli/edgedb_branch/edgedb_branch_merge.rst +++ b/docs/cli/edgedb_branch/edgedb_branch_merge.rst @@ -28,7 +28,7 @@ applying any new migrations from the target branch on the current branch. .. note:: When merging, the data of the current branch is preserved. This means that - if you switch to a branch ``main`` and run ``edgedb branch merge feature``, + if you switch to a branch ``main`` and run :gelcmd:`branch merge feature`, you will end up with a branch with the schema from ``main`` and any new migrations from ``feature`` and the data from ``main``. diff --git a/docs/cli/edgedb_connopts.rst b/docs/cli/edgedb_connopts.rst index 1832be94a8a..6cde004d227 100644 --- a/docs/cli/edgedb_connopts.rst +++ b/docs/cli/edgedb_connopts.rst @@ -25,8 +25,9 @@ Connection flags Specifies the named instance to connect to. The actual connection parameters for local and self-hosted instances are stored in ``/credentials`` and are usually created by - :ref:`ref_cli_edgedb_instance_create` or similar commands. Run ``edgedb - info`` to see the location of ```` on your machine. + :ref:`ref_cli_edgedb_instance_create` or similar commands. Run + :gelcmd:`info` to see the location of ```` on your + machine. |Gel| Cloud instance names are in the format ``/``. @@ -62,14 +63,15 @@ Connection flags :cli:synopsis:`-u , --user=` Connect to the database as the user :cli:synopsis:``. Defaults to the value of the ``EDGEDB_USER`` environment variable, or, - if not set, ``edgedb``. + if not set, ``admin``. :cli:synopsis:`-d , --database=` Specifies the name of the database to connect to. Defaults to the value of the ``EDGEDB_DATABASE`` environment variable. If that variable isn't set, - local instances will default to ``edgedb`` while remote instances will - default to the name provided when the link was created. This also includes - |Gel| Cloud instance links created via :ref:`ref_cli_edgedb_project_init`. + local instances will default to ``main`` (``edgedb`` for |EdgeDB| <= 50) + while remote instances will default to the name provided when the link + was created. This also includes |Gel| Cloud instance links created via + :ref:`ref_cli_edgedb_project_init`. .. note:: diff --git a/docs/cli/edgedb_database/edgedb_database_create.rst b/docs/cli/edgedb_database/edgedb_database_create.rst index 04a5472df90..1061b93dc8f 100644 --- a/docs/cli/edgedb_database/edgedb_database_create.rst +++ b/docs/cli/edgedb_database/edgedb_database_create.rst @@ -22,7 +22,7 @@ Create a new :ref:`database `. Description =========== -``edgedb database create`` is a terminal command equivalent to +:gelcmd:`database create` is a terminal command equivalent to :eql:stmt:`create database`. diff --git a/docs/cli/index.rst b/docs/cli/index.rst index a7f44fad4b1..5f6927ebaef 100644 --- a/docs/cli/index.rst +++ b/docs/cli/index.rst @@ -103,7 +103,7 @@ respectively: .. rubric:: Configure CLI and REPL -You can customize the behavior of the ``edgedb`` CLI and REPL with a +You can customize the behavior of the |gelcmd| CLI and REPL with a global configuration file. The file is called ``cli.toml`` and its location differs between operating systems. Use :ref:`ref_cli_edgedb_info` to find the "Config" directory on your diff --git a/docs/clients/js/reference.rst b/docs/clients/js/reference.rst index 0a6ea4b1d7a..74c960cbd87 100644 --- a/docs/clients/js/reference.rst +++ b/docs/clients/js/reference.rst @@ -22,8 +22,8 @@ Client If this parameter is a string it can represent either a DSN or an instance name: - * when the string does not start with ``gel://`` (or legacy - ``edgedb://``) it is a :ref:`name of an instance + * when the string does not start with ``gel://`` (or legacy |EdgeDB| + <= 5 ``edgedb://``) it is a :ref:`name of an instance `; * otherwise it specifies a single string in the connection URI format: diff --git a/docs/cloud/cli.rst b/docs/cloud/cli.rst index 73e8742154f..0647b67b74d 100644 --- a/docs/cloud/cli.rst +++ b/docs/cloud/cli.rst @@ -15,9 +15,9 @@ To use |Gel| Cloud via the CLI, first log in using but when interacting with Gel Cloud via a script or in CI, you'll instead set the ``EDGEDB_SECRET_KEY`` environment variable to your secret key. Generate a secret key in the Gel Cloud UI or by running - :ref:`ref_cli_edgedb_cloud_secretkey_create`. The ``edgedb cloud login`` - and ``edgedb cloud logout`` commands are not intended for use in this - context. + :ref:`ref_cli_edgedb_cloud_secretkey_create`. The :gelcmd:`cloud + login` and :gelcmd:`cloud logout` commands are not intended for use + in this context. Once your login is successful, you will be able to create an instance using either :ref:`ref_cli_edgedb_instance_create` or @@ -39,7 +39,7 @@ create a local project linked to your instance. $ edgedb project init \ --server-instance / - Alternatively, you can run ``edgedb project init`` *without* the + Alternatively, you can run :gelcmd:`project init` *without* the ``--server-instance`` option and enter an instance name in the ``/`` format when prompted interactively. @@ -54,19 +54,19 @@ create a local project linked to your instance. organization name (i.e., length of organization name + length of instance name must be fewer than 62 characters) -To use ``edgedb instance create``: +To use :gelcmd:`instance create`: .. code-block:: bash - $ edgedb instance create / + $ gel instance create / -To use ``edgedb project init``: +To use :gelcmd:`project init`: .. code-block:: bash - $ edgedb project init \ + $ gel project init \ --server-instance / -Alternatively, you can run ``edgedb project init`` *without* the +Alternatively, you can run :gelcmd:`project init` *without* the ``--server-instance`` option and enter an instance name in the ``/`` format when prompted interactively. diff --git a/docs/cloud/http_gql.rst b/docs/cloud/http_gql.rst index c6b88c3e711..885884f7d00 100644 --- a/docs/cloud/http_gql.rst +++ b/docs/cloud/http_gql.rst @@ -38,7 +38,7 @@ Instance URL ============ To determine the URL of an |Gel| Cloud instance, find the host by running -``edgedb instance credentials -I /``. Use the +:gelcmd:`instance credentials -I /`. Use the ``host`` and ``port`` from that table in the URL format above this note. Change the protocol to ``https`` since Gel Cloud instances are secured with TLS. diff --git a/edb/tools/docs/edb.py b/edb/tools/docs/edb.py index f691ed190c8..6514f102dc4 100644 --- a/edb/tools/docs/edb.py +++ b/edb/tools/docs/edb.py @@ -19,6 +19,8 @@ from __future__ import annotations +import re + from sphinx import domains as s_domains from docutils import nodes as d_nodes from docutils.parsers import rst as d_rst @@ -172,7 +174,19 @@ class GelCmdRole: def __call__( self, role, rawtext, text, lineno, inliner, options=None, content=None ): - text = f'gel {text.strip()}' + text = text.strip() + text = re.sub(r'(\n\s*)+', " ", text) + if text.startswith("edgedb"): + fn = inliner.document.current_source + raise Exception( + f"{fn}:{lineno} - :gelcmd:`{text}` - can't start with 'edgedb'" + ) + if text.startswith("gel ") or text == "gel": + fn = inliner.document.current_source + raise Exception( + f"{fn}:{lineno} - :gelcmd:`{text}` - can't start with 'gel'" + ) + text = f'gel {text}' node = d_nodes.literal(text, text) node["edb-gelcmd"] = "true" node["edb-gelcmd-top"] = "false" diff --git a/tests/test_docs_sphinx_ext.py b/tests/test_docs_sphinx_ext.py index 13e1d015284..6dbcfa37f2d 100644 --- a/tests/test_docs_sphinx_ext.py +++ b/tests/test_docs_sphinx_ext.py @@ -964,14 +964,13 @@ def test_sphinx_edb_brand_name_01(self): '''), ['Gel']) - - print(x) - def test_sphinx_edb_brand_name_02(self): src = ''' blah |gelcmd| blah 2 :gelcmd:`migrate --help` - + blah 3 :gelcmd:`migrate + --help + --foo` DONE ''' @@ -987,7 +986,8 @@ def test_sphinx_edb_brand_name_02(self): [@edb-gelcmd-top="true"] / text() '''), - ['gel']) + ['gel'] + ) self.assertEqual( x.xpath(''' @@ -997,5 +997,6 @@ def test_sphinx_edb_brand_name_02(self): [@edb-gelcmd-top="false"] / text() '''), - ['gel migrate --help']) + ['gel migrate --help', 'gel migrate --help --foo'] + )