From 210a1ef5f98723d170d079f59630ee29c40e6144 Mon Sep 17 00:00:00 2001 From: James Clarke Date: Wed, 6 Mar 2024 15:48:38 +0000 Subject: [PATCH] Docs links updates (#6993) * Update some docs links to use refs + add/remove host for some links to work with new docs site * Fix CI * Convert more client lib links to refs * Add query parameter types heading ref * Ignore missing ref errors for client docs --- docs/changelog/1_0_a2.rst | 4 ++-- docs/changelog/1_0_a3.rst | 2 +- docs/changelog/1_0_a4.rst | 2 +- docs/changelog/1_0_a5.rst | 5 ++--- docs/changelog/2_x.rst | 2 +- docs/clients/dart/index.rst | 2 ++ docs/clients/dotnet/index.rst | 2 ++ docs/clients/go/index.rst | 2 ++ docs/clients/rust/getting_started.rst | 14 ++++++-------- docs/clients/rust/transactions.rst | 10 ++++------ docs/conf.py | 2 ++ docs/edgeql/index.rst | 10 +++++----- docs/edgeql/parameters.rst | 2 ++ docs/edgeql/sets.rst | 4 ++-- docs/edgeql/transactions.rst | 10 ++++------ docs/guides/cloud/index.rst | 2 +- docs/guides/contributing/documentation.rst | 7 +++---- docs/guides/deployment/heroku.rst | 4 +--- docs/guides/migrations/guide.rst | 12 +++--------- docs/guides/tutorials/chatgpt_bot.rst | 8 ++++---- docs/guides/tutorials/cloudflare_workers.rst | 3 +-- .../tutorials/graphql_apis_with_strawberry.rst | 18 +++++++++--------- docs/guides/tutorials/nextjs.rst | 8 ++++---- docs/guides/tutorials/phoenix_github_oauth.rst | 4 ++-- .../tutorials/rest_apis_with_fastapi.rst | 6 +++--- docs/intro/clients.rst | 6 +++--- docs/intro/index.rst | 4 ++-- docs/intro/migrations.rst | 4 ++-- docs/intro/quickstart.rst | 14 +++++++------- docs/reference/connection.rst | 2 +- tests/test_docs.py | 17 ++++++++++++++++- 31 files changed, 100 insertions(+), 92 deletions(-) diff --git a/docs/changelog/1_0_a2.rst b/docs/changelog/1_0_a2.rst index 52d317d315f..2b15f77c5ce 100644 --- a/docs/changelog/1_0_a2.rst +++ b/docs/changelog/1_0_a2.rst @@ -7,7 +7,7 @@ =========== This changelog summarizes new features and breaking changes in -`EdgeDB 1.0 alpha 2 `_. +`EdgeDB 1.0 alpha 2 `_. New JavaScript Driver @@ -47,7 +47,7 @@ and it is ready for use: main(); -The documentation can be found `here `_. +The documentation can be found :ref:`here `. Standard Library diff --git a/docs/changelog/1_0_a3.rst b/docs/changelog/1_0_a3.rst index ba09e503917..b47dfbab9de 100644 --- a/docs/changelog/1_0_a3.rst +++ b/docs/changelog/1_0_a3.rst @@ -8,7 +8,7 @@ This changelog summarizes new features and breaking changes in `EdgeDB 1.0 alpha 3 "Proxima Centauri" -`_. +`_. CLI diff --git a/docs/changelog/1_0_a4.rst b/docs/changelog/1_0_a4.rst index aab1fd55d20..22f7d5637e4 100644 --- a/docs/changelog/1_0_a4.rst +++ b/docs/changelog/1_0_a4.rst @@ -8,7 +8,7 @@ This changelog summarizes new features and breaking changes in `EdgeDB 1.0 alpha 4 "Barnard's Star" -`_. +`_. EdgeQL diff --git a/docs/changelog/1_0_a5.rst b/docs/changelog/1_0_a5.rst index ea31a0fe742..7de1a2b48a6 100644 --- a/docs/changelog/1_0_a5.rst +++ b/docs/changelog/1_0_a5.rst @@ -7,7 +7,7 @@ =========== This changelog summarizes new features and breaking changes in -`EdgeDB 1.0 alpha 5 "Luhman" `_. +`EdgeDB 1.0 alpha 5 "Luhman" `_. EdgeQL @@ -108,8 +108,7 @@ CLI Bindings ======== -* Add transaction `API - `_ to JS binding +* Add transaction :ref:`API ` to JS binding (`#61 `_). Here's an example of using transactions: diff --git a/docs/changelog/2_x.rst b/docs/changelog/2_x.rst index bf90b535af3..4d3fc4525a4 100644 --- a/docs/changelog/2_x.rst +++ b/docs/changelog/2_x.rst @@ -91,7 +91,7 @@ upgrade. - ``edgedb@0.21.0`` * - :ref:`Python ` - ``edgedb@0.24.0`` - * - `Golang `_ + * - :ref:`Golang ` - ``edgedb@0.12.0`` * - `Rust `_ - ``edgedb-tokio@0.3.0`` diff --git a/docs/clients/dart/index.rst b/docs/clients/dart/index.rst index 7c154cd450b..073632aca15 100644 --- a/docs/clients/dart/index.rst +++ b/docs/clients/dart/index.rst @@ -1,3 +1,5 @@ +.. _edgedb-dart-intro: + ==== Dart ==== diff --git a/docs/clients/dotnet/index.rst b/docs/clients/dotnet/index.rst index df9789d7e4d..d5818190afe 100644 --- a/docs/clients/dotnet/index.rst +++ b/docs/clients/dotnet/index.rst @@ -1,3 +1,5 @@ +.. _edgedb-dotnet-intro: + ==== .NET ==== diff --git a/docs/clients/go/index.rst b/docs/clients/go/index.rst index 1edad36671f..fbc70705e0f 100644 --- a/docs/clients/go/index.rst +++ b/docs/clients/go/index.rst @@ -1,3 +1,5 @@ +.. _edgedb-go-intro: + == Go == diff --git a/docs/clients/rust/getting_started.rst b/docs/clients/rust/getting_started.rst index b29d18b3f3e..b73a1f78476 100644 --- a/docs/clients/rust/getting_started.rst +++ b/docs/clients/rust/getting_started.rst @@ -120,14 +120,14 @@ the `blog post introducing the EdgeDB projects CLI`_. and ``edgedb migrate``. - a ``/migrations`` folder with ``.edgeql`` files named starting at - ``00001``. These hold the `ddl`_ commands that were used to migrate your - schema. A new file shows up in this directory every time your schema - is migrated. + ``00001``. These hold the :ref:`ddl ` commands that were used + to migrate your schema. A new file shows up in this directory every time + your schema is migrated. If you are running EdgeDB 3.0 and above, you also have the option of using -the `edgedb watch`_ command. Doing so starts a long-running process that -keeps an eye on changes in ``/dbschema``, automatically applying these -changes in real time. +the :ref:`edgedb watch ` command. Doing so starts a +long-running process that keeps an eye on changes in ``/dbschema``, +automatically applying these changes in real time. Now that you have the right dependencies and an EdgeDB instance, you can create a client. @@ -135,9 +135,7 @@ you can create a client. .. _`blog post introducing the EdgeDB projects CLI`: https://www.edgedb.com/blog/introducing-edgedb-projects .. _`bridging methods`: https://tokio.rs/tokio/topics/bridging -.. _`ddl`: https://www.edgedb.com/docs/reference/ddl/index .. _`edgedb-derive`: https://docs.rs/edgedb-derive/latest/edgedb_derive/ .. _`edgedb-protocol`: https://docs.rs/edgedb-protocol/latest/edgedb_protocol .. _`edgedb-tokio`: https://docs.rs/edgedb-tokio/latest/edgedb_tokio -.. _`edgedb watch`: https://www.edgedb.com/docs/cli/edgedb_watch .. _`examples repo`: https://github.com/Dhghomon/edgedb_rust_client_examples \ No newline at end of file diff --git a/docs/clients/rust/transactions.rst b/docs/clients/rust/transactions.rst index 75d3e660201..6924b761f60 100644 --- a/docs/clients/rust/transactions.rst +++ b/docs/clients/rust/transactions.rst @@ -4,7 +4,7 @@ Transactions ------------ The client also has a ``.transaction()`` method that -allows for atomic `transactions`_. +allows for atomic :ref:`transactions `. Wikipedia has a good example of a scenario requiring a transaction which we can then implement: @@ -63,11 +63,9 @@ another's would look like this: .. note:: What often may seem to require an atomic transaction can instead be - achieved with links and `backlinks`_ which are both idiomatic and easy to - use in EdgeDB. For example, if one object holds a ``required link`` to two + achieved with links and :ref:`backlinks ` which + are both idiomatic and easy to use in EdgeDB. + For example, if one object holds a ``required link`` to two other objects and each of these two objects has a single backlink to the first one, simply updating the first object will effectively change the state of the other two instantaneously. - -.. _`backlinks`: https://www.edgedb.com/docs/edgeql/paths#backlinks -.. _`transactions`: https://www.edgedb.com/docs/edgeql/transactions \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 36f929e97c0..0d7e1847a33 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -108,6 +108,8 @@ # If true, keep warnings as "system message" paragraphs in the built documents. # keep_warnings = False +suppress_warnings = ['image.not_readable'] + # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False diff --git a/docs/edgeql/index.rst b/docs/edgeql/index.rst index 3fff601efe1..99ee4d9a460 100644 --- a/docs/edgeql/index.rst +++ b/docs/edgeql/index.rst @@ -65,15 +65,15 @@ like code and less like word soup. to write deep, performant queries that traverse links, no ``JOINs`` required. **Composable**. `Unlike SQL -`_, EdgeQL's syntax is -readily composable; queries can be cleanly nested without worrying about -Cartesian explosion. +`_, +EdgeQL's syntax is readily composable; queries can be cleanly nested without +worrying about Cartesian explosion. .. note:: For a detailed writeup on the design of SQL, see `We Can Do Better Than SQL - `_ on the EdgeDB - blog. + `_ + on the EdgeDB blog. Follow along ------------ diff --git a/docs/edgeql/parameters.rst b/docs/edgeql/parameters.rst index 1a579529a94..f799056944f 100644 --- a/docs/edgeql/parameters.rst +++ b/docs/edgeql/parameters.rst @@ -91,6 +91,8 @@ Refer to the Datatypes page of your preferred :ref:`client library language-native types. +.. _ref_eql_params_types: + Parameter types and JSON ------------------------ diff --git a/docs/edgeql/sets.rst b/docs/edgeql/sets.rst index 2b023892a68..768c9efa8ba 100644 --- a/docs/edgeql/sets.rst +++ b/docs/edgeql/sets.rst @@ -131,8 +131,8 @@ of data; in EdgeDB the absence of data is just an empty set. permeates all of SQL and is often handled inconsistently in different circumstances. A number of specific inconsistencies are documented in detail in the `We Can Do Better Than SQL - `_ post on the - EdgeDB blog. For broader context, see Tony Hoare's talk + `_ + post on the EdgeDB blog. For broader context, see Tony Hoare's talk `"The Billion Dollar Mistake" `_. diff --git a/docs/edgeql/transactions.rst b/docs/edgeql/transactions.rst index f201b778a91..df010ea18ce 100644 --- a/docs/edgeql/transactions.rst +++ b/docs/edgeql/transactions.rst @@ -96,8 +96,7 @@ Using the querybuilder: await query2.run(tx); }); -Full documentation at `Client Libraries > TypeScript/JS -`_; +Full documentation at :ref:`Client Libraries > TypeScript/JS `; Python ^^^^^^ @@ -113,8 +112,7 @@ Python filter .name = 'Customer2' set { bank_balance := .bank_balance +10 };""") -Full documentation at `Client Libraries > Python -`_; +Full documentation at :ref:`Client Libraries > Python `; Golang ^^^^^^ @@ -140,7 +138,7 @@ Golang log.Fatal(err) } -Full documentation at `Client Libraries > Go `_. +Full documentation at :ref:`Client Libraries > Go `. Rust ^^^^ @@ -164,4 +162,4 @@ Rust .await .expect("Transaction should have worked"); -Full documentation at `Client Libraries > Rust `_. +Full documentation at :ref:`Client Libraries > Rust `. diff --git a/docs/guides/cloud/index.rst b/docs/guides/cloud/index.rst index 21ec06c8358..63c03fc46cd 100644 --- a/docs/guides/cloud/index.rst +++ b/docs/guides/cloud/index.rst @@ -36,7 +36,7 @@ better! `_ for information on what may be causing it. * Report any bugs you find by `submitting a support ticket - `_. Note: when using EdgeDB Cloud + `_. Note: when using EdgeDB 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. diff --git a/docs/guides/contributing/documentation.rst b/docs/guides/contributing/documentation.rst index 4bb831bd864..e71acbf21be 100644 --- a/docs/guides/contributing/documentation.rst +++ b/docs/guides/contributing/documentation.rst @@ -85,13 +85,12 @@ find it alongside the client itself. These clients will also have documentation stubs inside the edgedb repository directing you to the documentation's location. -The `EdgeDB tutorial `_ is part of `our web +The `EdgeDB tutorial `_ is part of `our web site repository `_. You'll find it in `the tutorial directory `_. -Finally, our book for beginners titled `Easy EdgeDB -`_ lives in `its own repo -`_. +Finally, our book for beginners titled `Easy EdgeDB `_ lives in +`its own repo `_. How to Build It diff --git a/docs/guides/deployment/heroku.rst b/docs/guides/deployment/heroku.rst index 9e549e371c3..7358c4e6312 100644 --- a/docs/guides/deployment/heroku.rst +++ b/docs/guides/deployment/heroku.rst @@ -42,14 +42,12 @@ First copy the code, initialize a new git repo, and create a new heroku app. $ heroku apps:create --buildpack heroku/nodejs $ edgedb project init --non-interactive -If you are using the `JS query builder for EdgeDB `_ then +If you are using the :ref:`JS query builder for EdgeDB ` then you will need to check the ``dbschema/edgeql-js`` directory in to your git repo after running ``yarn edgeql-js``. The ``edgeql-js`` command cannot be run during the build step on Heroku because it needs access to a running EdgeDB instance which is not available at build time on Heroku. -.. _js-query-builder: https://www.edgedb.com/docs/clients/js/index - .. code-block:: bash $ yarn install && npx @edgedb/generate edgeql-js diff --git a/docs/guides/migrations/guide.rst b/docs/guides/migrations/guide.rst index 7187be4d981..72dd9363e53 100644 --- a/docs/guides/migrations/guide.rst +++ b/docs/guides/migrations/guide.rst @@ -612,7 +612,7 @@ require appending ``--allow-empty`` to the command. Just do the following: schema file manually, copy the suggested name into the migration hash and type ``edgedb migrate`` again. -The `EdgeDB tutorial `_ is a good example of a database +The `EdgeDB tutorial `_ is a good example of a database set up with both a schema migration and a data migration. Setting up a database with `schema changes in one file and default data in a second file `_ is a nice way to separate the two operations @@ -1204,7 +1204,7 @@ want to accept all of the suggestions provided by the server. This process is in fact still used to migrate even today; the CLI just facilitates it by making it easy to respond to the generated suggestions. -`Early EdgeDB migrations took place inside a transaction `_ +:ref:`Early EdgeDB migrations took place inside a transaction ` handled by the user that essentially went like this: .. code-block:: @@ -1353,11 +1353,5 @@ migration and give it a proper ``.edgeql`` file in the same way we did above in the "So you really wanted to use DDL but now regret it?" section. -.. lint-off - .. _rfc: https://github.com/edgedb/rfcs/blob/master/text/1000-migrations.rst -.. _transaction: https://www.edgedb.com/docs/reference/ddl/migrations -.. _tutorial: https://www.edgedb.com/tutorial -.. _tutorial_files: https://github.com/edgedb/website/tree/main/content/tutorial/dbschema/migrations - -.. lint-on \ No newline at end of file +.. _tutorial_files: https://github.com/edgedb/website/tree/main/content/tutorial/dbschema/migrations \ No newline at end of file diff --git a/docs/guides/tutorials/chatgpt_bot.rst b/docs/guides/tutorials/chatgpt_bot.rst index 4424c7bddea..f550c8a4e4a 100644 --- a/docs/guides/tutorials/chatgpt_bot.rst +++ b/docs/guides/tutorials/chatgpt_bot.rst @@ -457,8 +457,8 @@ database because of the ``pgvector`` extension. In order to use it in our schema, we have to activate the ``ext::pgvector`` module with ``using extension pgvector`` at the beginning of the schema file. This module gives us access to the ``ext::pgvector::vector`` data type as well as few similarity functions and -indexes we can use later to retrieve embeddings. Read our `pgvector -documentation `_ for more details +indexes we can use later to retrieve embeddings. Read our :ref:`pgvector +documentation ` for more details on the extension. Just below that, we can start building our module by creating a new scalar @@ -603,8 +603,8 @@ libraries that will help us. The ``@edgedb/generate`` package provides a set of code generation tools that are useful when developing an EdgeDB-backed applications with -TypeScript/JavaScript. We're going to write queries using our `query builder -`_, but before we can, we +TypeScript/JavaScript. We're going to write queries using our +:ref:`query builder `, but before we can, we need to run the query builder generator. .. code-block:: bash diff --git a/docs/guides/tutorials/cloudflare_workers.rst b/docs/guides/tutorials/cloudflare_workers.rst index 993c099783a..0c920b4484b 100644 --- a/docs/guides/tutorials/cloudflare_workers.rst +++ b/docs/guides/tutorials/cloudflare_workers.rst @@ -27,11 +27,10 @@ Prerequisites Ensure you have the following installed: - `Node.js`_ -- `EdgeDB CLI`_ +- :ref:`EdgeDB CLI ` .. _Sign up for a Cloudflare account: https://dash.cloudflare.com/sign-up .. _Node.js: https://nodejs.org/en/ -.. _EdgeDB CLI: https://www.edgedb.com/docs/intro/cli Setup and configuration ----------------------- diff --git a/docs/guides/tutorials/graphql_apis_with_strawberry.rst b/docs/guides/tutorials/graphql_apis_with_strawberry.rst index 2a855b82e5e..572bfceb75b 100644 --- a/docs/guides/tutorials/graphql_apis_with_strawberry.rst +++ b/docs/guides/tutorials/graphql_apis_with_strawberry.rst @@ -9,7 +9,7 @@ extension. It enables you to expose GraphQL-driven CRUD APIs for all object types, their properties, links, and aliases. This opens up the scope for creating backend-less applications where the users will directly communicate with the database. You can learn more about that in the -`GraphQL `_ section of the docs. +:ref:`GraphQL ` section of the docs. However, as of now, EdgeDB is not ready to be used as a standalone backend. You shouldn't expose your EdgeDB instance directly to the application’s frontend; @@ -23,7 +23,7 @@ like schema, query, mutation, resolver, validator, etc, and have used GraphQL with some other technology before. We'll build the same movie organization system that we used in the Flask -`tutorial `_ +:ref:`tutorial ` and expose the objects and relationships as a GraphQL API. Using the GraphQL interface, you'll be able to fetch, create, update, and delete movie and actor objects in the database. `Strawberry `_ is a Python @@ -378,7 +378,7 @@ This exposes the webserver in port 5000. Now, in your browser, go to find that the HTTP basic auth requires us to provide the username and password. .. image:: - https://www.edgedb.com/docs/tutorials/strawberry/http_basic.png + /docs/tutorials/strawberry/http_basic.png :alt: HTTP basic auth prompt :width: 100% @@ -389,7 +389,7 @@ like this: .. image:: - https://www.edgedb.com/docs/tutorials/strawberry/graphiql.png + /docs/tutorials/strawberry/graphiql.png :alt: GraphiQL interface :width: 100% @@ -410,7 +410,7 @@ following query does that: The following response will appear on the right panel of the GraphiQL explorer: .. image:: - https://www.edgedb.com/docs/tutorials/strawberry/query_actors.png + /docs/tutorials/strawberry/query_actors.png :alt: Query actors :width: 100% @@ -494,7 +494,7 @@ and show all three attributes— ``name``, ``age``, and ``height`` of the create actor in the response payload. Here's the response: .. image:: - https://www.edgedb.com/docs/tutorials/strawberry/create_actor.png + /docs/tutorials/strawberry/create_actor.png :alt: Create an actor :width: 100% @@ -503,7 +503,7 @@ to fetch the actors. Running the ``ActorQuery`` will give you the following response: .. image:: - https://www.edgedb.com/docs/tutorials/strawberry/query_actors_2.png + /docs/tutorials/strawberry/query_actors_2.png :alt: Query actors :width: 100% @@ -704,7 +704,7 @@ actor ``Robert Downey Jr.`` with the movie: It'll return: .. image:: - https://www.edgedb.com/docs/tutorials/strawberry/create_movie.png + /docs/tutorials/strawberry/create_movie.png :alt: Create a movie :width: 100% @@ -727,7 +727,7 @@ Now you can fetch the movies with a simple query like this one: You'll then see an output similar to this: .. image:: - https://www.edgedb.com/docs/tutorials/strawberry/query_movies.png + /docs/tutorials/strawberry/query_movies.png :alt: Query movies :width: 100% diff --git a/docs/guides/tutorials/nextjs.rst b/docs/guides/tutorials/nextjs.rst index 6c5dc9f4423..3d007e930fe 100644 --- a/docs/guides/tutorials/nextjs.rst +++ b/docs/guides/tutorials/nextjs.rst @@ -117,7 +117,7 @@ something like this. .. image:: - https://www.edgedb.com/docs/tutorials/nextjs/basic_home.png + /docs/tutorials/nextjs/basic_home.png :alt: Basic blog homepage with static content :width: 100% @@ -441,7 +441,7 @@ We're also using a utility called ``$infer`` to extract the inferred type of this query. In VSCode you can hover over ``Posts`` to see what this type is. .. image:: - https://www.edgedb.com/docs/tutorials/nextjs/inference.png + /docs/tutorials/nextjs/inference.png :alt: Inferred type of posts query :width: 100% @@ -549,7 +549,7 @@ Now, click on one of the blog post links on the homepage. This should bring you to ``/post/``, which should display something like this: .. image:: - https://www.edgedb.com/docs/tutorials/nextjs/post.png + /docs/tutorials/nextjs/post.png :alt: Basic blog homepage with static content :width: 100% @@ -643,7 +643,7 @@ When prompted: tutorial. .. image:: - https://www.edgedb.com/docs/tutorials/nextjs/env.png + /docs/tutorials/nextjs/env.png :alt: Setting environment variables in Vercel :width: 100% diff --git a/docs/guides/tutorials/phoenix_github_oauth.rst b/docs/guides/tutorials/phoenix_github_oauth.rst index 34b67ef1b2e..5c09f020771 100644 --- a/docs/guides/tutorials/phoenix_github_oauth.rst +++ b/docs/guides/tutorials/phoenix_github_oauth.rst @@ -9,8 +9,8 @@ Phoenix In this tutorial, we'll look at how you can create an application with authorization through GitHub using -`Phoenix `_ and `the official EdgeDB Elixir -driver `_. +`Phoenix `_ and :ref:`the official EdgeDB Elixir +driver `. This tutorial is a simplified version of the `LiveBeats `_ application from diff --git a/docs/guides/tutorials/rest_apis_with_fastapi.rst b/docs/guides/tutorials/rest_apis_with_fastapi.rst index 05de37c74a2..fb651016e0b 100644 --- a/docs/guides/tutorials/rest_apis_with_fastapi.rst +++ b/docs/guides/tutorials/rest_apis_with_fastapi.rst @@ -1133,7 +1133,7 @@ your browser and head over to API navigator like this: .. image:: - https://www.edgedb.com/docs/tutorials/fastapi/openapi.png + /docs/tutorials/fastapi/openapi.png :alt: FastAPI docs navigator :width: 100% @@ -1143,7 +1143,7 @@ and then click on the **Try it out** button. You can do it in the UI as follows: .. image:: - https://www.edgedb.com/docs/tutorials/fastapi/put.png + /docs/tutorials/fastapi/put.png :alt: FastAPI docs PUT events API :width: 100% @@ -1151,7 +1151,7 @@ Clicking the **execute** button will make the request and return the following payload: .. image:: - https://www.edgedb.com/docs/tutorials/fastapi/put_result.png + /docs/tutorials/fastapi/put_result.png :alt: FastAPI docs PUT events API result :width: 100% diff --git a/docs/intro/clients.rst b/docs/intro/clients.rst index 5e6f2787b24..c5c6c16e2a6 100644 --- a/docs/intro/clients.rst +++ b/docs/intro/clients.rst @@ -35,12 +35,12 @@ To execute queries from your application code, use one of EdgeDB's *client libraries* for the following languages. - :ref:`JavaScript/TypeScript ` -- `Go `__ +- :ref:`Go ` - :ref:`Python ` - :ref:`Rust ` -- `C# and F# `__ +- :ref:`C# and F# ` - :ref:`Java ` -- `Dart `__ +- :ref:`Dart ` - :ref:`Elixir ` Usage diff --git a/docs/intro/index.rst b/docs/intro/index.rst index 94d5fd0d9d5..40b760c1f5f 100644 --- a/docs/intro/index.rst +++ b/docs/intro/index.rst @@ -19,8 +19,8 @@ Get Started clients EdgeDB is a next-generation `graph-relational database -`_ designed as a spiritual -successor to the relational database. +`_ designed +as a spiritual successor to the relational database. It inherits the strengths of SQL databases: type safety, performance, reliability, and transactionality. But instead of modeling data in a diff --git a/docs/intro/migrations.rst b/docs/intro/migrations.rst index 5d3cf2618da..db844230a1c 100644 --- a/docs/intro/migrations.rst +++ b/docs/intro/migrations.rst @@ -300,5 +300,5 @@ Further reading Further information can be found in the :ref:`CLI reference ` or the `Beta 1 blog post -`_, which -describes the design of the migration system. \ No newline at end of file +`_, +which describes the design of the migration system. \ No newline at end of file diff --git a/docs/intro/quickstart.rst b/docs/intro/quickstart.rst index 079a8a4e94d..a27f8691e4d 100644 --- a/docs/intro/quickstart.rst +++ b/docs/intro/quickstart.rst @@ -438,12 +438,12 @@ EdgeDB UI is a useful development tool, but in practice your application will likely be using one of EdgeDB's *client libraries* to execute queries. EdgeDB provides official libraries for :ref:`JavaScript/TypeScript `, -`Go `__, +:ref:`Go `, :ref:`Python `, :ref:`Rust `, -`C# and F# `__, +:ref:`C# and F# `, :ref:`Java `, -`Dart `__, and +:ref:`Dart `, and :ref:`Elixir `. Check out the :ref:`Clients @@ -478,8 +478,8 @@ and used a client library. concepts. - To start building an application using the language of your choice, check out - our client libraries: :ref:`JavaScript/TypeScript `, `Go - `__, :ref:`Python `, :ref:`Rust - `, `C# and F# `__, :ref:`Java - `, `Dart `__, and :ref:`Elixir + our client libraries: :ref:`JavaScript/TypeScript `, :ref:`Go + `, :ref:`Python `, :ref:`Rust + `, :ref:`C# and F# `, :ref:`Java + `, :ref:`Dart `, and :ref:`Elixir `. diff --git a/docs/reference/connection.rst b/docs/reference/connection.rst index 0e282b8aca9..048bc877076 100644 --- a/docs/reference/connection.rst +++ b/docs/reference/connection.rst @@ -148,7 +148,7 @@ Let's dig into each of these a bit more. instance's credentials, and connect automatically. For more information on how this works, check out the `release post - `_ for ``edgedb project``. + `_ for ``edgedb project``. .. _ref_reference_connection_priority: diff --git a/tests/test_docs.py b/tests/test_docs.py index 1839938224f..7d540f6af2b 100644 --- a/tests/test_docs.py +++ b/tests/test_docs.py @@ -464,7 +464,6 @@ def test_doc_full_build(self): sys.executable, '-m', 'sphinx', '-n', - '-W', # fail on warnings '-b', 'xml', '-q', '-D', 'master_doc=index', @@ -482,3 +481,19 @@ def test_doc_full_build(self): f'STDOUT:\n{proc.stdout}\n\n' f'STDERR:\n{proc.stderr}\n' ) + + errors = [] + ignored_errors = re.compile( + r'^.* WARNING: undefined label: edgedb-' + r'(python|js|go|dart|dotnet|elixir|java)-.*$' + ) + for line in proc.stderr.splitlines(): + if not ignored_errors.match(line): + errors.append(line) + + if len(errors) > 0: + errors = '\n'.join(errors) + raise AssertionError( + f'Unable to build docs with Sphinx.\n\n' + f'{errors}\n\n' + )