docs: move all documentation content into the docs subdirectory

docs/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,3 @@
+<!--
+When adding a new doc section or page, please add an entry to releases/upcoming.rst.
+-->

docs/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+- package-ecosystem: github-actions
+  directory: /
+  schedule:
+    interval: weekly

docs/.github/workflows/ci.yaml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches:
+    - main
+    - v*
+  pull_request:
+    branches:
+    - main
+    - v*
+
+jobs:
+  build:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: cachix/install-nix-action@v24
+    - run: nix-env -f default.nix -iA build
+    - run: postgrest-docs-build
+
+  spellcheck:
+    name: Run spellcheck
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: cachix/install-nix-action@v24
+    - run: nix-env -f default.nix -iA spellcheck
+    - run: postgrest-docs-spellcheck
+
+  dictcheck:
+    name: Run dictcheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v24
+      - run: nix-env -f 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@v4
+    - uses: cachix/install-nix-action@v24
+    - run: nix-env -f default.nix -iA linkcheck
+    - run: postgrest-docs-linkcheck
+

docs/.gitignore

@@ -0,0 +1,8 @@
+_build
+Pipfile.lock
+*.aux
+*.log
+diagrams/db.pdf
+misspellings
+unuseddict
+.history

docs/.readthedocs.yaml

@@ -0,0 +1,10 @@
+version: 2
+sphinx:
+  configuration: docs/conf.py
+python:
+   install:
+   - requirements: requirements.txt
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"

docs/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/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2014 Joe Nelson
+Copyright (c) 2019 Steve Chavez
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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/default.nix

@@ -0,0 +1,95 @@
+let
+  # Commit of the Nixpkgs repository that we want to use.
+  nixpkgsVersion = {
+    date = "2023-03-25";
+    rev = "dbf5322e93bcc6cfc52268367a8ad21c09d76fea";
+    tarballHash = "0lwk4v9dkvd28xpqch0b0jrac4xl9lwm6snrnzx8k5lby72kmkng";
+  };
+
+  # Nix files that describe the Nixpkgs repository. We evaluate the expression
+  # using `import` below.
+  pkgs = import
+    (fetchTarball {
+      url = "https://github.com/nixos/nixpkgs/archive/${nixpkgsVersion.rev}.tar.gz";
+      sha256 = nixpkgsVersion.tarballHash;
+    })
+    { };
+
+  python = pkgs.python3.withPackages (ps: [ ps.sphinx ps.sphinx_rtd_theme ps.livereload ps.sphinx-tabs ps.sphinx-copybutton ps.sphinxext-opengraph ]);
+in
+rec {
+  inherit pkgs;
+
+  build =
+    pkgs.writeShellScriptBin "postgrest-docs-build"
+      ''
+        set -euo pipefail
+
+        # clean previous build, otherwise some errors might be supressed
+        rm -rf _build
+
+        ${python}/bin/sphinx-build --color -W -b html -a -n docs _build
+      '';
+
+  serve =
+    pkgs.writeShellScriptBin "postgrest-docs-serve"
+      ''
+        set -euo pipefail
+
+        # livereload_docs.py needs to find "sphinx-build"
+        PATH=${python}/bin:$PATH
+
+        ${python}/bin/python livereload_docs.py
+      '';
+
+  spellcheck =
+    pkgs.writeShellScriptBin "postgrest-docs-spellcheck"
+      ''
+        set -euo pipefail
+
+        FILES=$(find docs -type f -iname '*.rst' | tr '\n' ' ')
+
+        cat $FILES \
+         | grep -v '^\(\.\.\|  \)' \
+         | sed 's/`.*`//g' \
+         | ${pkgs.aspell}/bin/aspell -d ${pkgs.aspellDicts.en}/lib/aspell/en_US -p ./postgrest.dict list \
+         | sort -f \
+         | tee misspellings
+        test ! -s misspellings
+      '';
+
+  # dictcheck detects obsolete entries in postgrest.dict, that are not used anymore
+  dictcheck =
+    pkgs.writeShellScriptBin "postgrest-docs-dictcheck"
+      ''
+        set -euo pipefail
+
+        FILES=$(find docs -type f -iname '*.rst' | tr '\n' ' ')
+
+        cat postgrest.dict \
+         | tail -n+2 \
+         | tr '\n' '\0' \
+         | xargs -0 -n 1 -i \
+           sh -c "grep \"{}\" $FILES > /dev/null || echo \"{}\"" \
+         | tee unuseddict
+        test ! -s unuseddict
+      '';
+
+  linkcheck =
+    pkgs.writeShellScriptBin "postgrest-docs-linkcheck"
+      ''
+        set -euo pipefail
+
+        ${python}/bin/sphinx-build --color -b linkcheck docs _build
+      '';
+
+  check =
+    pkgs.writeShellScriptBin "postgrest-docs-check"
+      ''
+        set -euo pipefail
+        ${build}/bin/postgrest-docs-build
+        ${dictcheck}/bin/postgrest-docs-dictcheck
+        ${linkcheck}/bin/postgrest-docs-linkcheck
+        ${spellcheck}/bin/postgrest-docs-spellcheck
+      '';
+}

docs/diagrams/README.md

@@ -0,0 +1,42 @@
+## 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 diagrams/film.er -o docs/_static/film.png
+```
+
+The fonts used belong to the GNU FreeFont family. You can download them here: http://ftp.gnu.org/gnu/freefont/
+
+## 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 ../docs/_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/boxoffice.er

@@ -0,0 +1,15 @@
+entity {font: "FreeSans"}
+relationship {font: "FreeMono"}
+
+[Box_Office]
+*bo_date
+*+film_id
+gross_revenue
+
+[Films]
+*id
++director_id
+title
+`...`
+
+Box_Office +--1 Films

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/employees.er

@@ -0,0 +1,12 @@
+# Build using: -e ortho
+
+entity {font: "FreeSans"}
+relationship {font: "FreeMono"}
+
+[Employees]
+*id
+first_name
+last_name
++supervisor_id
+
+Employees 1--* Employees