Quartz 4

EdgeDB.com site repo notes

4 min read

Requirements

  • Requires Go 1.17.1
  • Using gobrew to manage multiple versions
    • Canonical method of using go install doesn’t work since the go command will still run the initial version.

Development

  1. Start EdgeDB instance via env EDGEDB_DEBUG_HTTP_INJECT_CORS=1 edgedb instance start --foreground -I tutorial
  2. Start development server with yarn dev

Notes

  • Sometimes requires re-running setup if you start getting XML errors culminating in a Javascript memory error when trying to run the dev server via yarn dev. The error looks like this:
FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
  • yarn regenGrammar requires the Python virtual environment from the dev server build to run properly. Without that, it will fail to find the edb module. If you try to run it without this, it will still write the empty output of the command to components/code/auto-grammar.js, blanking out the file. Then, the site will fail because Prism will not have the sdl language. The grammars are checked into source control on the edgedb.com repo, so you’ll need to check them out again to restore. You’ll get this error:
TypeError: Cannot read properties of undefined (reading 'rest')
[nextjs]     at Object.tokenize (/Users/raddevon/Documents/projects/edgedb/edgedb.com/node_modules/prismjs/prism.js:697:23)
[nextjs]     at annotateCode (webpack-internal:///./components/annotatedCodeBlock/index.tsx:60:70)
[nextjs]     at eval (webpack-internal:///./components/annotatedCodeBlock/index.tsx:160:60)
[nextjs]     at Object.useMemo (/Users/raddevon/Documents/projects/edgedb/edgedb.com/node_modules/react-dom/cjs/react-dom-server.node.development.js:1582:19)
[nextjs]     at useMemo (/Users/raddevon/Documents/projects/edgedb/edgedb.com/node_modules/react/cjs/react.development.js:1532:21)
[nextjs]     at AnnotatedCodeBlock (webpack-internal:///./components/annotatedCodeBlock/index.tsx:160:53)
[nextjs]     at processChild (/Users/raddevon/Documents/projects/edgedb/edgedb.com/node_modules/react-dom/cjs/react-dom-server.node.development.js:3353:14)
[nextjs]     at resolve (/Users/raddevon/Documents/projects/edgedb/edgedb.com/node_modules/react-dom/cjs/react-dom-server.node.development.js:3270:5)
[nextjs]     at ReactDOMServerRenderer.render (/Users/raddevon/Documents/projects/edgedb/edgedb.com/node_modules/react-dom/cjs/react-dom-server.node.development.js:3753:22)
[nextjs]     at ReactDOMServerRenderer.read (/Users/raddevon/Documents/projects/edgedb/edgedb.com/node_modules/react-dom/cjs/react-dom-server.node.development.js:3690:29)
  • The build may fail if the documentation references methods it cannot find. To resolve, remove or comment out the references to those methods. They are marked in documentation as :<binding>:method:. The error will reference the method that can’t be found like so:
Error: Error: Command failed: ./.venv/bin/sphinx-build -D extensions=edgedbsite.sphinx_edbxml,edgedbsite.dotnetdomain,sphinx.ext.autodoc,sphinx.ext.todo,sphinx.ext.viewcode,edb.tools.docs,sphinxcontrib.asyncio,sphinx.ext.intersphinx,sphinx_code_tabs -b edge-xml -q -D master_doc=index -W -n -a /var/folders/jv/96l1fwz17pn1j2fl879wd0840000gn/T/tmp-49732-nHfs9ghPgrQ5 .build-cache/_xml/docs

Warning, treated as error:
Failed to resolve method EdgeDB.EdgeDBClient.WithGlobals(Dictionary<string,object>)
  • When building documentation, the build may fail if one document is not linked from another. The error message will say that a document was not found in a toctree. This can happen when a new client is added because the link has not yet been added upstream in the main edgedb repo yet. In that specific case, open edgedb/docs/clients/index.rst and add the path for the new client’s index to the toctree at the bottom of that document.
  • If the Sphinx build fails without referencing a particular problem, it could be a problem with the Python environment. Try python --version to confirm it is working. If it is, re-run yarn setup to ensure the dependencies are installed and current.
  • The build may fail because of a change in dartdoc output that we haven’t yet adapted to. It looks like this:
Error: expected "tr" tag
  at /Users/raddevon/Documents/projects/edgedb/edgedb.com/dataBuild/dartdocs.ts:394:21
  at Array.map (<anonymous>)
  at nodeToRst (/Users/raddevon/Documents/projects/edgedb/edgedb.com/dataBuild/dartdocs.ts:392:12)
  at /Users/raddevon/Documents/projects/edgedb/edgedb.com/dataBuild/dartdocs.ts:315:27
  at Array.map (<anonymous>)
  at nodeToRst (/Users/raddevon/Documents/projects/edgedb/edgedb.com/dataBuild/dartdocs.ts:315:12)
  at processClientPage (/Users/raddevon/Documents/projects/edgedb/edgedb.com/dataBuild/dartdocs.ts:139:5)
  at async Promise.all (index 1)
  at async buildDartDocs (/Users/raddevon/Documents/projects/edgedb/edgedb.com/dataBuild/dartdocs.ts:37:3)
  at async /Users/raddevon/Documents/projects/edgedb/edgedb.com/dataBuild/docs.ts:184:13

In this case, fall back to version 2.17 of dart. Install this in homebrew by first tapping the official tap with brew tap dart-lang/dart. Then install with brew install dart@2.17. Then add to path with echo 'export PATH="/opt/homebrew/opt/dart@2.17/bin:$PATH"' >> ~/.zshrc and source ~/.zshrc.

Deployment

prod branch is used as the “Production” branch on Vercel. To deploy changes:

  1. merge your changes into master
  2. wait for Vercel deployment to succeed and confirm working
  3. pull any changes on master
  4. checkout the prod branch
  5. pull any changes on prod
  6. git merge master
  7. git push origin prod (or git push origin master:prod and pull master again)

For documentation in other repos

Generalized documentation is kept in the site repo, but documentation specific to other projects is kept in that project’s repo. When changes to another repo’s documentation has been merged, it should be automatically deployed via the docs Github workflow.

Check Vercel. If that deployment is not in progress, manually trigger a redeploy.

  1. Log into the Vercel EdgeDB website dashboard
  2. Click through on the name of the most recent deployment (at the top middle of the web site’s card in the dashboard UI)
  3. Drop down the three dots menu and click “Redeploy”

Graph View

Backlinks