doc/user
This is the root directory of the Materialize user docs, which are rendered by the Hugo site in locally or at https://materialize.io/docs.
Instructions for previewing the documentation locally are contained in .
Writing & managing docs
Railroad diagrams for SQL grammar
Railroad diagrams consist of two parts:
bnf
files that describe the grammar you want to convey in a railroad diagram.html
files that contain ansvg
generated by https://www.bottlecaps.de/rr/ui
To generate diagrams
- Modify/create
bnf
files in/www/layouts/partials/sql-grammar/bnf
. - Ensure your diagram looks like you want using https://www.bottlecaps.de/rr/ui.
- Go to
/www/util/rr-diagram-gen/
- Run
make
.
You can now include the diagram on a page using:
{{< diagram "SOME_DIAGRAM.html" >}}
- Replace
<
with<
and>
with>
. SOME_DIAGRAM
will be the name of thebnf
file, and should be anhtml
file visible in/www/layouts/partials/sql-grammar/rr-diagrams
.
Why is the world like this?
Because our diagrams rely on Hugo’s partials
features, the diagram files are
maintained in the /www
dir (the actual Hugo site), but referenced as if they
were local (through the magic of symlinks).
Function + Operator docs
The Functions you see at www/docs/sql/functions/
are populated from
www/data/sql_funcs.json
. Unfortunately this means that they’re ad hoc and are
not actually generated from the Materialize source code.
As new functions get added, this file must be manually updated. The idea here is to structure functions by their input type (whereas operators are grouped by their output type), largely influenced by the way that Postgres structures their function docs.
If you see the need to add or change the grouping here, don’t be shy.
Syntax highlighting
Most code samples contain two components: the SQL query you want to run and the expected output.
Due to some design choice in the syntax highlighter used by Hugo, you must select a language to highlight the code blocks in or none of the expected formatting gets applied.
For SQL blocks, the natural choice is sql
. For the response blocks, which
don’t need to be/shouldn’t be syntax highlighted, you can use any
non-recognized string as the language (i.e. anything that isn’t popular
programming language). For expressivity, we chose nofmt
.