Collection of docs fixes

docs/.gitignore

@@ -1,3 +1,4 @@
+_build
 Pipfile.lock
 *.aux
 *.log

docs/conf.py

@@ -48,20 +48,16 @@
 # The master toctree document.
 master_doc = "index"
 
+# This is overriden by readthedocs with the version tag anyway
+version = "devel"
+# To avoid repetition in <title> we set this to an empty string.
+release = ""
+
 # General information about the project.
-project = "PostgREST"
+project = "PostgREST " + version
 author = "Joe Nelson, Steve Chavez"
 copyright = "2017, " + author
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = "12.1"
-# The full version, including alpha/beta/rc tags.
-release = "12.1-dev"
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -117,7 +113,7 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {"display_version": False}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

docs/explanations/install.rst

@@ -163,14 +163,15 @@ If you want to have a visual overview of your API in your browser you can add sw
 
 .. code-block:: yaml
 
-  swagger:
-    image: swaggerapi/swagger-ui
-    ports:
-      - "8080:8080"
-    expose:
-      - "8080"
-    environment:
-      API_URL: http://localhost:3000/
+  # in services:
+    swagger:
+      image: swaggerapi/swagger-ui
+      ports:
+        - "8080:8080"
+      expose:
+        - "8080"
+      environment:
+        API_URL: http://localhost:3000/
 
 With this you can see the swagger-ui in your browser on port 8080.
 
@@ -181,10 +182,6 @@ Building from Source
 
 When a pre-built binary does not exist for your system you can build the project from source.
 
-.. note::
-
-  We discourage building and using PostgREST on **Alpine Linux** because of a reported GHC memory leak on that platform.
-
 You can build PostgREST from source with `Stack <https://github.com/commercialhaskell/stack>`_. It will install any necessary Haskell dependencies on your system.
 
 * `Install Stack <https://docs.haskellstack.org/en/stable/README/#how-to-install-stack>`_ for your platform

docs/how-tos/providing-images-for-img.rst

@@ -81,9 +81,11 @@ First, in addition to the minimal example, we need to store the media types and
 .. code-block:: postgres
 
    alter table files
-     add column type text,
+     add column type text generated always as (byteamagic_mime(substr(blob, 0, 4100))) stored,
      add column name text;
 
+This uses the :code:`byteamagic_mime()` function from the `pg_byteamagic extension <https://github.com/nmandery/pg_byteamagic>`_ to automatically generate the type in the :code:`files` table. To guess the type of a file, it's generally enough to look at the beginning of the file, which is more efficient.
+
 Next, we set modify the function to set the content type and filename.
 We use this opportunity to configure some basic, client-side caching.
 For production, you probably want to configure additional caches, e.g. on the :ref:`reverse proxy <nginx>`.

docs/how-tos/sql-user-management-using-postgres-users-and-passwords.rst

@@ -54,7 +54,7 @@ Concerning the `pgjwt extension <https://github.com/michelp/pgjwt>`_, please cf.
 
 In order to be able to work with postgres' SCRAM-SHA-256 password hashes, we also need the PBKDF2 key derivation function. Luckily there is `a PL/pgSQL implementation on stackoverflow <https://stackoverflow.com/a/72805848>`_:
 
-.. code-block:: plpgsql
+.. code-block:: postgres
 
   CREATE FUNCTION basic_auth.pbkdf2(salt bytea, pw text, count integer, desired_length integer, algorithm text) RETURNS bytea
       LANGUAGE plpgsql IMMUTABLE
@@ -120,7 +120,7 @@ In order to be able to work with postgres' SCRAM-SHA-256 password hashes, we als
 Analogous to :ref:`sql_user_management` creates the function :code:`basic_auth.user_role`, we create a helper function to check the user's password, here with another name and signature (since we want the username, not an email address).
 But contrary to :ref:`sql_user_management`, this function does not use a dedicated :code:`users` table with passwords, but instead utilizes the built-in table `pg_catalog.pg_authid <https://www.postgresql.org/docs/current/catalog-pg-authid.html>`_:
 
-.. code-block:: plpgsql
+.. code-block:: postgres
 
   CREATE FUNCTION basic_auth.check_user_pass(username text, password text) RETURNS name
       LANGUAGE sql
@@ -160,7 +160,7 @@ Logins
 As described in :ref:`client_auth`, we'll create a JWT token inside our login function. Note that you'll need to adjust the secret key which is hard-coded in this example to a secure (at least thirty-two character) secret of your choosing.
 
 
-.. code-block:: plpgsql
+.. code-block:: postgres
 
   CREATE TYPE basic_auth.jwt_token AS (
     token text

docs/how-tos/sql-user-management.rst

@@ -28,7 +28,7 @@ First we'll need a table to keep track of our users:
 
 We would like the role to be a foreign key to actual database roles, however PostgreSQL does not support these constraints against the :code:`pg_roles` table. We'll use a trigger to manually enforce it.
 
-.. code-block:: plpgsql
+.. code-block:: postgres
 
   create or replace function
   basic_auth.check_role_exists() returns trigger as $$
@@ -50,7 +50,7 @@ We would like the role to be a foreign key to actual database roles, however Pos
 
 Next we'll use the pgcrypto extension and a trigger to keep passwords safe in the :code:`users` table.
 
-.. code-block:: plpgsql
+.. code-block:: postgres
 
   create extension if not exists pgcrypto;
 
@@ -72,7 +72,7 @@ Next we'll use the pgcrypto extension and a trigger to keep passwords safe in th
 
 With the table in place we can make a helper to check a password against the encrypted column. It returns the database role for a user if the email and password are correct.
 
-.. code-block:: plpgsql
+.. code-block:: postgres
 
   create or replace function
   basic_auth.user_role(email text, pass text) returns name