Quartz 4

EdgeDB documentation on documentation

7 min read

Task

EdgeDB web site call 2023-02-08

  • Expand Contributing documentation
    • First page, building
    • Second page, documentation
      • particularly, versioning directives
      • edgeql directives
      • Sphinx- link to markup
      • rest- link to markup
      • Approach to versioning
    • Have a call with Victor, Sully, Yury to discuss
  • Yury contracting with another writer to help with Rust documentation
  • Put together thoughts about documentation versioning
Link to original

Notes

Prism languages

Custom

  • edgeql = sdl
  • edgeql-synopsis = sdl-synopsis = cli-synopsis
  • eql_function
  • eql_operator

Directives

  • .. lint-on/lint-off
  • .. code-block: [<language>]
    • bash- include prompt and optionally output
    • javascript
    • edgeql- Used when showing queries
    • sdl- Used when defining schema
    • edgeql-repl- include prompt and optionally output
    • add -diff to any? then add +/- inline to show additions/removals
    • Leave out language to just get a formatted monospaced block
    • “Copy” button added to the block when a language is specified
      • “Copy” button on shell or REPL blocks copies only the command without the prompt and output
  • .. toctree::- If not marked orphan, page must be linked in one of these
    • :maxdepth: 3
    • :hidden:
      • Not shown on page but still in sidebar
      • Pages in hidden toc will still be a part of forward/back buttons at the bottom of the page
    • .. eql:synopsis::- block used for formal reference
    • Can also look like this: :eql:synopsis:`configure session`
      • What does it do?
      • Sometimes doesn’t have the name or backticks. Why?
    • first three letters represent the section of the docs
      • What are all the values?
  • .. cli:synopsis::
  • .. note:: and how we use it
    • Same for .. warning::, .. important::
    • Can add text on the same line with the directives to position it next to the colored label text
  • .. include:: ../stdlib/constraint_table.rst
  • Tabs
.. tabs::

  .. code-tab:: typescript

    import createClient from 'edgedb';

    const baseClient = createClient()
    const clientWithGlobals = baseClient.withGlobals({
      current_user_id: '2141a5b4-5634-4ccc-b835-437863534c51',
    });

    await clientWithGlobals.query(`select global current_user_id;`);

  .. code-tab:: python

    from edgedb import create_client

    client = create_client().with_globals({
        'current_user_id': '580cc652-8ab8-4a20-8db9-4c79a4b1fd81'
    })

    result = client.query("""
        select global current_user_id;
    """)
    print(result)

  .. code-tab:: go

    package main

    import (
      "context"
      "fmt"
      "log"

      "github.com/edgedb/edgedb-go"
    )

    func main() {
      ctx := context.Background()
      client, err := edgedb.CreateClient(ctx, edgedb.Options{})
      if err != nil {
        log.Fatal(err)
      }
      defer client.Close()

      id, err := edgedb.ParseUUID("2141a5b4-5634-4ccc-b835-437863534c51")
      if err != nil {
        log.Fatal(err)
      }

      var result edgedb.UUID
      err = client.
        WithGlobals(map[string]interface{}{"current_user": id}).
        QuerySingle(ctx, "SELECT global current_user;", &result)
      if err != nil {
        log.Fatal(err)
      }

      fmt.Println(result)
    }

  .. code-tab:: edgeql

    set global current_user_id := <uuid>'2141a5b4-5634-4ccc-b835-437863534c51';

  • .. before line- comment
    • when to use? ever?
  • .. rubric:: <text>- Creates a bolded heading
    • when to use?
  • .. eql:section-intro-page:: edgeql
    • What does this do?

Tables and lists

.. list-table::

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

  • :class: funcoptable
.. 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`

====================================== =============================

YouTube embedding

.. lint-off

.. raw:: html

    <div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; height: auto;">
       <iframe src="https://www.youtube.com/embed/OZ_UURzDkow" frameborder="0" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe>
    </div>

.. lint-on

Versioning

  • .. versionadded:: 2.0, .. versionchanged:: 3.0- Control when and how a block is displayed depending on the user’s selection in the version dropdown

Misc

  • linking? (or direct to Sphinx docs?)
    • Maybe mention the preferred way (target inline) and cases for doing it the other way (separate target)
    • When separating target, where does the target go? Bottom of section? Below paragraph containing link?
  • Call out inline code (``code``) and difference from markdown
    • When to use inline vs. code block
  • :orphan:- page does not have to be linked
  • :eql:type:`type` /:eql:func:`function` and the like
    • Creates link to that type or function’s documentation
    • :eql:stmt:`update`
    • :eql:constraint:`exclusive`
  • :eql:gh:`6a7c6787` /:eql:gh:`#3771`
    • Makes a link to GitHub commit or issue
      • on the edgedb/edgedb repo?
  • Section markup hierarchy
    • We’re not consistent on this. We probably need to be?
  • ref links and markers
    • how we use them
    • Example: :ref:`connection options <ref_cli_edgedb_connopts>`
    • each page gets a ref marker at the top
    • sections get ref markers if and when they need them
  • How to build and view docs locally
  • *<word>*- italics
  • **<word>**- bold
  • :edb-alt-title: Databases
    • What does this do?
  • :eql-statement:
    • What does this do?
  • Emojis- Do we use and when?
    • One example of current usage at ddl/access_policies
  • :eql-haswith:
    • What does this do?
  • :index: poly polymorphism nested shapes
    • Add search terms that don’t appear (in the text? title?)
  • Locations of other documentations that are pulled into the build
  • When does a page get a right-side on-page menu?

Guidelines

  • When something you want to do in docs is not specifically mentioned here, try to mirror something similar that already exists in our documentation
  • Be careful about where you put your changes, whether that’s where a new page goes in the document tree or where a new paragraph goes on an existing page.
    • Ask, “When a person has the problem I anticipate that the documentation solves, where would they look?”
  • If your documentation change doesn’t solve a problem, it may not be necessary.
    • This isn’t intended to trivialize things like typos, incorrect punctuation, and poor word choice. Those issues can make our docs harder to read, which is a problem that needs solving.

Questions

  • ----------
    • What should this be? I thought it would be a horizontal rule, but it doesn’t render.
    • Currently unused. No need to document this.
  • versionchanged appears to be a block, but versionadded is not. How does versionadded work? What does it apply to? How does it know what to hide?
    • until next heading of the same level or higher?
    • versionchanged and versionadded are both builtin sphinx directives, except we have custom overrides for them that makes them behave slightly differently to how they’re documented in sphinx. They both have to have a version argument, and can both be used similar to a note block if they have content. versionadded currently also has different behaviour if it doesn’t have content, and is used either as the first directive of a page (has to be before any refs at the top to make sure they get properly attached to the page title), immediately after a section header, or inside a desc block. In these cases it won’t get rendered, but instead marks the page, section or desc block with the version, which then means it will be affected by the version switcher.
  • Can -diff be added to any language designator in the code block directive?
    • As far as I remember: yes. The -diff suffix is handled by the code block rendering code, and if it’s present each line of the code is expected to start with + , - , or which will get stripped away, and the line will be rendered green or red (or normal).
  • Can also look like this: :eql:synopsis:`configure session`
    • What does the backtick portion do?
    • Sometimes doesn’t have the name or backticks. Why?
    • :eql:synopsis:configure session is broken into three parts - :eql: which is part of the EdgeQL Sphinx domain, synopsis which is the directive, and then configure session is the reference, correct.
    • **:eql: domain is documented at the top of edgedb/eql.py at master · edgedb/edgedb
  • :eql:gh:`6a7c6787` /:eql:gh:`#3771`
    • first three letters represent the section of the docs
      • What are all the values?
    • Makes a link to GitHub commit or issue
      • on the edgedb/edgedb repo?
    • I believe it works for any repo, edgedb/edgedb is just the default if not specified, which I think you can do like this: :eql:gh:edgedb/edgedb-js/#123
  • :edb-alt-title: Databases
    • What does this do?
    • The alt title is used in place of the page title when rendered. The url and nav still use the real title, so it can be used if you want a longer title on the page that doesn’t fit in the nav, like this page for example: https://www.edgedb.com/docs/datamodel/computeds
  • When does a page get a right-side on-page menu?
    • **When there’s space 😄. So when the window is both wide enough and the list of subheadings is short enough that it will fit without scrolling.
  • .. rubric:: <text>- Creates a bolded heading
    • when to use?
  • .. eql:section-intro-page:: edgeql

Graph View

Backlinks