docs: merge postgrest-docs into the core repository

.github/workflows/docs.yaml

@@ -16,8 +16,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: cachix/install-nix-action@v25
-    - run: nix-env -f docs/default.nix -iA build
+    - name: Setup Nix Environment
+      uses: ./.github/actions/setup-nix
+      with:
+        tools: docs
     - run: postgrest-docs-build
     - run: git diff --exit-code HEAD locales || echo "Please commit changes to the locales/ folder after running postgrest-docs-build."
 
@@ -26,17 +28,21 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: cachix/install-nix-action@v25
-    - run: nix-env -f docs/default.nix -iA spellcheck
+    - name: Setup Nix Environment
+      uses: ./.github/actions/setup-nix
+      with:
+        tools: docs
     - run: postgrest-docs-spellcheck
 
   dictcheck:
     name: Run dictcheck
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: cachix/install-nix-action@v25
-      - run: nix-env -f docs/default.nix -iA dictcheck
+      - name: Setup Nix Environment
+        uses: ./.github/actions/setup-nix
+        with:
+          tools: docs
       - run: postgrest-docs-dictcheck
 
   linkcheck:
@@ -45,7 +51,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: cachix/install-nix-action@v25
-    - run: nix-env -f docs/default.nix -iA linkcheck
+    - name: Setup Nix Environment
+      uses: ./.github/actions/setup-nix
+      with:
+        tools: docs
     - run: postgrest-docs-linkcheck
-

BACKERS.md

@@ -32,7 +32,7 @@ PostgREST ongoing development is only possible thanks to our Sponsors and Backer
       </td>
       <td align="center" valign="middle">
         <a href="https://supabase.io?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage" target="_blank">
-          <img width="296px" src="https://raw.githubusercontent.com/PostgREST/postgrest/main/static/supabase.png">
+          <img width="296px" src="static/supabase.png">
         </a>
       </td>
       <td align="center" valign="middle">
@@ -75,12 +75,12 @@ PostgREST ongoing development is only possible thanks to our Sponsors and Backer
     <tr>
       <td align="center" valign="middle">
         <a href="https://www.timescale.com?utm_campaign=postgrest&utm_source=sponsor&utm_medium=referral&utm_content=github" target="_blank">
-          <img width="222px" src="https://raw.githubusercontent.com/PostgREST/postgrest/main/static/timescaledb.png">
+          <img width="222px" src="static/timescaledb.png">
         </a>
       </td>
       <td align="center" valign="middle">
         <a href="https://tryretool.com/?utm_source=sponsor&utm_campaign=postgrest" target="_blank">
-          <img max-width="222px" height="88" src="https://raw.githubusercontent.com/PostgREST/postgrest/main/static/retool.png">
+          <img max-width="222px" height="88" src="static/retool.png">
         </a>
       </td>
       <td align="center" valign="middle">

README.md

@@ -1,4 +1,4 @@
-![Logo](static/bigger-logo.png "Logo")
+![Logo](static/postgrest.png "Logo")
 
 [![Donate](https://img.shields.io/badge/Donate-Patreon-orange.svg?colorB=F96854)](https://www.patreon.com/postgrest)
 [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/postgrest)
@@ -43,7 +43,7 @@ API than you are likely to write from scratch.
       </td>
       <td align="center" valign="middle">
         <a href="https://supabase.io?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage" target="_blank">
-          <img width="296px" src="https://raw.githubusercontent.com/PostgREST/postgrest/main/static/supabase.png">
+          <img width="296px" src="static/supabase.png">
         </a>
       </td>
       <td align="center" valign="middle">

default.nix

@@ -124,6 +124,10 @@ rec {
   devTools =
     pkgs.callPackage nix/tools/devTools.nix { inherit tests style devCabalOptions hsie withTools; };
 
+  # Documentation tools.
+  docs =
+    pkgs.callPackage nix/tools/docs.nix { };
+
   # Load testing tools.
   loadtest =
     pkgs.callPackage nix/tools/loadtest.nix { inherit withTools; };

docs/.gitignore

@@ -5,5 +5,4 @@ Pipfile.lock
 _diagrams/db.pdf
 misspellings
 unuseddict
-.history
 *.mo

docs/README.md

@@ -2,17 +2,7 @@
 
 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.
+To build the docs locally, see [the Nix development readme](/nix/README.md#documentation).
 
 ## Documentation structure
 

docs/conf.py

@@ -58,9 +58,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "11.2"
+version = "12.1"
 # The full version, including alpha/beta/rc tags.
-release = "11.2.0"
+release = "12.1-dev"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -5,7 +5,7 @@ PostgREST Documentation
 
 .. container:: image-container
 
-  .. figure:: _static/logo.png
+  .. figure:: ../static/postgrest.png
 
 .. image:: https://img.shields.io/github/stars/postgrest/postgrest.svg?style=social
   :target: https://github.com/PostgREST/postgrest
@@ -34,29 +34,29 @@ Sponsors
 
 .. container:: image-container
 
-  .. image:: _static/cybertec-new.png
+  .. image:: ../static/cybertec-new.png
     :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest
     :width:  13em
 
-  .. image:: _static/gnuhost.png
+  .. image:: ../static/gnuhost.png
     :target: https://gnuhost.eu/?utm_source=sponsor&utm_campaign=postgrest
     :width:  13em
 
-  .. image:: _static/neon.jpg
+  .. image:: ../static/neon.jpg
     :target: https://neon.tech/?utm_source=sponsor&utm_campaign=postgrest
     :width:  13em
 
   |
 
-  .. image:: _static/code-build.webp
+  .. image:: ../static/code-build.webp
     :target: https://code.build/?utm_source=sponsor&utm_campaign=postgrest
     :width:  13em
 
-  .. image:: _static/supabase.png
+  .. image:: ../static/supabase.png
     :target: https://supabase.com/?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage
     :width:  13em
 
-  .. image:: _static/tembo.png
+  .. image:: ../static/tembo.png
     :target: https://tembo.io/?utm_source=sponsor&utm_campaign=postgrest
     :width:  13em
 

nix/README.md

@@ -248,6 +248,27 @@ $ nix-shell --run postgrest-style
 There is also `postgrest-style-check` that exits with a non-zero exit code if
 the check resulted in any uncommitted changes. It's mostly useful for CI.
 
+## Documentation
+
+The following commands can help you when working on the PostgREST docs:
+
+```bash
+# Build the docs
+[nix-shell]$ postgrest-docs-build
+
+# Build the docs and start a livereload server on `http://localhost:5500`
+[nix-shell]$ postgrest-docs-serve
+
+# Run aspell, to verify spelling mistakes
+[nix-shell]$ postgrest-docs-spellcheck
+
+# Detect obsolete entries in postgrest.dict
+[nix-shell]$ postgrest-docs-dictcheck
+
+# Build and run all the validation scripts
+[nix-shell]$ postgrest-docs-check
+```
+
 ## General development tools
 
 Tools like `postgrest-build`, `postgrest-run`, `postgrest-repl` etc. are simple wrappers around