Merge branch 'docs/v10.2' into rel-10.2

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,5 +2,5 @@
 When submitting a new feature or fix:
 
 - Add a new entry to the CHANGELOG - https://github.com/PostgREST/postgrest/blob/main/CHANGELOG.md#unreleased
-- If relevant, update the docs     - https://github.com/PostgREST/postgrest-docs
+- If relevant, update the docs
 -->

.github/workflows/docs.yaml

@@ -0,0 +1,50 @@
+name: Docs
+
+on:
+  push:
+    branches:
+    - main
+    - rel-*
+  pull_request:
+    branches:
+    - main
+    - rel-*
+
+jobs:
+  build:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: cachix/install-nix-action@v22
+    - run: nix-env -f docs/default.nix -iA build
+    - run: postgrest-docs-build
+
+  spellcheck:
+    name: Run spellcheck
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: cachix/install-nix-action@v22
+    - run: nix-env -f docs/default.nix -iA spellcheck
+    - run: postgrest-docs-spellcheck
+
+  dictcheck:
+    name: Run dictcheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: cachix/install-nix-action@v22
+      - run: nix-env -f docs/default.nix -iA dictcheck
+      - run: postgrest-docs-dictcheck
+
+  linkcheck:
+    name: Run linkcheck
+    if: github.base_ref == 'main'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: cachix/install-nix-action@v22
+    - run: nix-env -f docs/default.nix -iA linkcheck
+    - run: postgrest-docs-linkcheck
+

.readthedocs.yaml

@@ -0,0 +1,6 @@
+version: 2
+sphinx:
+  configuration: docs/conf.py
+python:
+   install:
+   - requirements: docs/requirements.txt

CONTRIBUTING.md

@@ -0,0 +1,3 @@
+This repository follows the same contribution guidelines as the main PostgREST repository contribution guidelines:
+
+https://github.com/PostgREST/postgrest/blob/main/.github/CONTRIBUTING.md

docs/.gitignore

@@ -0,0 +1,6 @@
+_build
+Pipfile.lock
+*.aux
+*.log
+_diagrams/db.pdf
+misspellings

docs/README.md

@@ -0,0 +1,20 @@
+# PostgREST documentation https://postgrest.org/
+
+PostgREST docs use the reStructuredText format, check this [cheatsheet](https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst) to get acquainted with it.
+
+To build the docs locally, use [nix](https://nixos.org/nix/):
+
+```bash
+  nix-shell
+```
+
+Once in the nix-shell you have the following commands available:
+
+- `postgrest-docs-build`: Build the docs.
+- `postgrest-docs-serve`: Build the docs and start a livereload server on `http://localhost:5500`.
+- `postgrest-docs-spellcheck`: Run aspell.
+
+## Documentation structure
+
+This documentation is structured according to tutorials-howtos-topics-references. For more details on the rationale of this structure, 
+see https://www.divio.com/blog/documentation.

docs/_diagrams/README.md

@@ -0,0 +1,40 @@
+## ERD
+
+The ER diagrams were created with https://github.com/BurntSushi/erd/.
+
+You can go download erd from https://github.com/BurntSushi/erd/releases and then do:
+
+```bash
+./erd_static-x86-64 -i film.er -o ../_static/film.png
+```
+
+## LaTeX
+
+The schema structure diagram is done with LaTeX. You can use a GUI like https://www.mathcha.io/editor to create the .tex file.
+
+Then use this command to generate the png file.
+
+```bash
+pdflatex --shell-escape -halt-on-error db.tex
+
+## and move it to the static folder(it's not easy to do it in one go with the pdflatex)
+mv db.png ../_static/
+```
+
+LaTeX is used because it's a tweakable plain text format.
+
+You can install the full latex suite with `nix`:
+
+```
+nix-env -iA texlive.combined.scheme-full
+```
+
+To tweak the file with a live reload environment use:
+
+```bash
+# open the pdf(zathura used as an example)
+zathura db.pdf &
+
+# live reload with entr
+echo db.tex | entr pdflatex --shell-escape -halt-on-error db.tex
+```

docs/_diagrams/db.tex

@@ -0,0 +1,71 @@
+\documentclass[convert]{standalone}
+\usepackage{amsmath}
+\usepackage{tikz}
+\usepackage{mathdots}
+\usepackage{yhmath}
+\usepackage{cancel}
+\usepackage{color}
+\usepackage{siunitx}
+\usepackage{array}
+\usepackage{multirow}
+\usepackage{amssymb}
+\usepackage{gensymb}
+\usepackage{tabularx}
+\usepackage{booktabs}
+\usetikzlibrary{fadings}
+\usetikzlibrary{patterns}
+\usetikzlibrary{shadows.blur}
+\usetikzlibrary{shapes}
+
+\begin{document}
+
+\newcommand\customScale{0.35}
+
+\begin{tikzpicture}[x=0.75pt,y=0.75pt,yscale=-1,xscale=1, scale=\customScale, every node/.style={scale=\customScale}]
+
+%Shape: Can [id:dp7234864758664346]
+\draw  [fill={rgb, 255:red, 47; green, 97; blue, 144 }  ,fill opacity=1 ] (497.5,51.5) -- (497.5,255.5) .. controls (497.5,275.66) and (423.18,292) .. (331.5,292) .. controls (239.82,292) and (165.5,275.66) .. (165.5,255.5) -- (165.5,51.5) .. controls (165.5,31.34) and (239.82,15) .. (331.5,15) .. controls (423.18,15) and (497.5,31.34) .. (497.5,51.5) .. controls (497.5,71.66) and (423.18,88) .. (331.5,88) .. controls (239.82,88) and (165.5,71.66) .. (165.5,51.5) ;
+%Shape: Rectangle [id:dp7384065579958246]
+\draw  [fill={rgb, 255:red, 236; green, 227; blue, 227 }  ,fill opacity=1 ] (189,115) -- (252.5,115) -- (252.5,155) -- (189,155) -- cycle ;
+%Shape: Rectangle [id:dp24763906430298177]
+\draw  [fill={rgb, 255:red, 236; green, 227; blue, 227 }  ,fill opacity=1 ] (292,118) -- (362,118) -- (362,158) -- (292,158) -- cycle ;
+%Shape: Rectangle [id:dp3775601612537265]
+\draw  [fill={rgb, 255:red, 236; green, 227; blue, 227 }  ,fill opacity=1 ] (397,114) -- (467,114) -- (467,154) -- (397,154) -- cycle ;
+%Shape: Rectangle [id:dp7071457022893852]
+\draw  [fill={rgb, 255:red, 248; green, 231; blue, 28 }  ,fill opacity=1 ] (269,199) -- (397.5,199) -- (397.5,273) -- (269,273) -- cycle ;
+%Straight Lines [id:da8846759047437789]
+\draw    (268,234) -- (226.44,155.77) ;
+\draw [shift={(225.5,154)}, rotate = 422.02] [color={rgb, 255:red, 0; green, 0; blue, 0 }  ][line width=0.75]    (10.93,-3.29) .. controls (6.95,-1.4) and (3.31,-0.3) .. (0,0) .. controls (3.31,0.3) and (6.95,1.4) .. (10.93,3.29)   ;
+%Straight Lines [id:da6908444738113828]
+\draw    (309.5,198) -- (307.6,161) ;
+\draw [shift={(307.5,159)}, rotate = 447.06] [color={rgb, 255:red, 0; green, 0; blue, 0 }  ][line width=0.75]    (10.93,-3.29) .. controls (6.95,-1.4) and (3.31,-0.3) .. (0,0) .. controls (3.31,0.3) and (6.95,1.4) .. (10.93,3.29)   ;
+%Straight Lines [id:da7168757864413169]
+\draw    (398.5,233) -- (431.72,154.84) ;
+\draw [shift={(432.5,153)}, rotate = 473.03] [color={rgb, 255:red, 0; green, 0; blue, 0 }  ][line width=0.75]    (10.93,-3.29) .. controls (6.95,-1.4) and (3.31,-0.3) .. (0,0) .. controls (3.31,0.3) and (6.95,1.4) .. (10.93,3.29)   ;
+%Up Down Arrow [id:dp14059754167108496]
+\draw  [fill={rgb, 255:red, 126; green, 211; blue, 33 }  ,fill opacity=1 ] (312.5,288.5) -- (330,273) -- (347.5,288.5) -- (338.75,288.5) -- (338.75,319.5) -- (347.5,319.5) -- (330,335) -- (312.5,319.5) -- (321.25,319.5) -- (321.25,288.5) -- cycle ;
+
+% Text Node
+\draw (201,129) node [anchor=north west][inner sep=0.75pt]   [align=left] {tables};
+% Text Node
+\draw (307,130) node [anchor=north west][inner sep=0.75pt]   [align=left ] {tables};
+% Text Node
+\draw (414,127) node [anchor=north west][inner sep=0.75pt]   [align=left] {tables};
+% Text Node
+\draw (272,203) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 0; green, 0; blue, 0 }  ,opacity=1 ] [align=center] { \\ views \\ + \\ \ \ stored procedures};
+
+% Text Node
+\draw (322,178) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{api}};
+% Text Node
+\draw (190,97) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{internal}};
+% Text Node
+\draw (300,99) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{private}};
+% Text Node
+\draw (417,101) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{core}};
+% Text Node
+\draw (358,306) node [anchor=north west][inner sep=0.75pt]   [align=left] {REST};
+
+\end{tikzpicture}
+
+
+\end{document}

docs/_diagrams/film.er

@@ -0,0 +1,40 @@
+[Films]
+*id
++director_id
+title
+year
+rating
+language
+
+[Directors]
+*id
+first_name
+last_name
+
+[Actors]
+*id
+first_name
+last_name
+
+[Roles]
+*+film_id
+*+actor_id
+character
+
+[Competitions]
+*id
+name
+year
+
+[Nominations]
+*+competition_id
+*+film_id
+rank
+
+Roles *--1 Actors
+Roles *--1 Films
+
+Nominations *--1 Competitions
+Nominations *--1 Films
+
+Films *--1 Directors

docs/_diagrams/orders.er

@@ -0,0 +1,15 @@
+[Addresses]
+*id
+name
+city
+state
+postal_code
+
+[Orders]
+*id
+name
++billing_address_id
++shipping_address_id
+
+Orders *--1 Addresses
+Orders *--1 Addresses

docs/_static/css/custom.css

@@ -0,0 +1,67 @@
+.wy-nav-content {
+  max-width: initial;
+}
+
+#postgrest-documentation > h1 {
+  display: none;
+}
+
+div.wy-menu.rst-pro {
+  display: none !important;
+}
+
+div.highlight {
+  background: #fff !important;
+}
+
+div.line-block {
+  margin-bottom: 0px !important;
+}
+
+#sponsors {
+  text-align: center;
+}
+
+#sponsors h2 {
+  text-align: left;
+}
+
+#sponsors img{
+  margin: 10px;
+}
+
+#thanks{
+  text-align: center;
+}
+
+#thanks img{
+  margin: 10px;
+}
+
+#thanks h2{
+  text-align: left;
+}
+
+#thanks p{
+  text-align: left;
+}
+
+#thanks ul{
+  text-align: left;
+}
+
+.image-container {
+  max-width: 800px;
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+  margin-bottom: 24px;
+}
+
+.wy-table-responsive table td {
+    white-space: normal !important;
+}
+
+.wy-table-responsive {
+    overflow: visible !important;
+}