Add curl examples alongside http snippets

admin.rst

@@ -43,15 +43,27 @@ Block Full-Table Operations
 
 Each table in the admin-selected schema gets exposed as a top level route. Client requests are executed by certain database roles depending on their authentication. All HTTP verbs are supported that correspond to actions permitted to the role. For instance if the active role can drop rows of the table then the DELETE verb is allowed for clients. Here's an API request to delete old rows from a hypothetical logs table:
 
-.. code-block:: http
+.. tabs::
 
-  DELETE /logs?time=lt.1991-08-06 HTTP/1.1
+  .. code-tab:: http
+
+    DELETE /logs?time=lt.1991-08-06 HTTP/1.1
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/logs?time=lt.1991-08-06" -X DELETE
 
 However it's very easy to delete the **entire table** by omitting the query parameter!
 
-.. code-block:: http
+.. tabs::
 
-  DELETE /logs HTTP/1.1
+  .. code-tab:: http
+
+    DELETE /logs HTTP/1.1
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/logs" -X DELETE
 
 This can happen accidentally such as by switching a request from a GET to a DELETE. To protect against accidental operations use the `pg-safeupdate <https://github.com/eradman/pg-safeupdate>`_ PostgreSQL extension. It raises an error if UPDATE or DELETE are executed without specifying conditions. To install it you can use the `PGXN <https://pgxn.org/>`_ network:
 
@@ -293,10 +305,17 @@ Alternate URL Structure
 
 As discussed in :ref:`singular_plural`, there are no special URL forms for singular resources in PostgREST, only operators for filtering. Thus there are no URLs like :code:`/people/1`. It would be specified instead as
 
-.. code:: http
+.. tabs::
 
-  GET /people?id=eq.1 HTTP/1.1
-  Accept: application/vnd.pgrst.object+json
+  .. code-tab:: http
+
+    GET /people?id=eq.1 HTTP/1.1
+    Accept: application/vnd.pgrst.object+json
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/people?id=eq.1" \
+      -H "Accept: application/vnd.pgrst.object+json"
 
 This allows compound primary keys and makes the intent for singular response independent of a URL convention.
 

auth.rst

@@ -150,10 +150,17 @@ Client Auth
 
 To make an authenticated request the client must include an :code:`Authorization` HTTP header with the value :code:`Bearer <jwt>`. For instance:
 
-.. code:: http
+.. tabs::
 
-  GET /foo HTTP/1.1
-  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiamRvZSIsImV4cCI6MTQ3NTUxNjI1MH0.GYDZV3yM0gqvuEtJmfpplLBXSGYnke_Pvnl0tbKAjB4
+  .. code-tab:: http
+
+    GET /foo HTTP/1.1
+    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiamRvZSIsImV4cCI6MTQ3NTUxNjI1MH0.GYDZV3yM0gqvuEtJmfpplLBXSGYnke_Pvnl0tbKAjB4
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/foo" \
+      -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiamRvZSIsImV4cCI6MTQ3NTUxNjI1MH0.GYDZV3yM0gqvuEtJmfpplLBXSGYnke_Pvnl0tbKAjB4"
 
 The ``Bearer`` header value can be used with or without capitalization(``bearer``).
 
@@ -422,11 +429,19 @@ As described in `JWT from SQL`_, we'll create a JWT inside our login function. N
 
 An API request to call this function would look like:
 
-.. code:: http
+.. tabs::
 
-  POST /rpc/login HTTP/1.1
+  .. code-tab:: http
 
-  { "email": "foo@bar.com", "pass": "foobar" }
+    POST /rpc/login HTTP/1.1
+
+    { "email": "foo@bar.com", "pass": "foobar" }
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/rpc/login" \
+      -X POST -H "Content-Type: application/json" \
+      -d '{ "email": "foo@bar.com", "pass": "foobar" }'
 
 The response would look like the snippet below. Try decoding the token at `jwt.io <https://jwt.io/>`_. (It was encoded with a secret of :code:`reallyreallyreallyreallyverysafe` as specified in the SQL code above. You'll want to change this secret in your app!)
 

conf.py

@@ -28,7 +28,10 @@ import os
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+  'sphinx_tabs.tabs',
+  'sphinx_copybutton'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -293,3 +296,5 @@ def setup(app):
 # taken from https://github.com/sphinx-doc/sphinx/blob/82dad44e5bd3776ecb6fd8ded656bc8151d0e63d/sphinx/util/requests.py#L42
 user_agent = 'Mozilla/5.0 (X11; Linux x86_64; rv:25.0) Gecko/20100101 Firefox/25.0'
 
+# sphinx-tabs configuration
+sphinx_tabs_disable_tab_closing = True

default.nix

@@ -15,7 +15,10 @@ let
     })
     { };
 
-  python = pkgs.python3.withPackages (ps: [ ps.sphinx ps.sphinx_rtd_theme ps.livereload ]);
+  sphinxTabsPkg = ps: ps.callPackage ./extensions/sphinx-tabs.nix {};
+  sphinxCopybuttonPkg = ps: ps.callPackage ./extensions/sphinx-copybutton.nix {};
+
+  python = pkgs.python3.withPackages (ps: [ ps.sphinx ps.sphinx_rtd_theme ps.livereload (sphinxTabsPkg ps) (sphinxCopybuttonPkg ps) ]);
 in
 {
   inherit pkgs;

extensions/sphinx-copybutton.nix

@@ -0,0 +1,33 @@
+{ lib
+, buildPythonPackage
+, fetchFromGitHub
+, sphinx
+}:
+
+buildPythonPackage rec {
+  pname = "sphinx-copybutton";
+  version = "0.4.0";
+
+  src = fetchFromGitHub {
+    owner = "executablebooks";
+    repo = "sphinx-copybutton";
+    rev = "v${version}";
+    sha256 = "sha256-vrEIvQeP7AMXSme1PBp0ox5k8Q1rz+1cbHIO+o17Jqc=";
+    fetchSubmodules = true;
+  };
+
+  propagatedBuildInputs = [
+    sphinx
+  ];
+
+  doCheck = false; # no tests
+
+  pythonImportsCheck = [ "sphinx_copybutton" ];
+
+  meta = with lib; {
+    description = "A small sphinx extension to add a \"copy\" button to code blocks";
+    homepage = "https://github.com/executablebooks/sphinx-copybutton";
+    license = licenses.mit;
+    maintainers = with maintainers; [ Luflosi ];
+  };
+}

extensions/sphinx-tabs.nix

@@ -0,0 +1,29 @@
+{ lib
+, buildPythonPackage
+, fetchPypi
+, sphinx
+}:
+
+buildPythonPackage rec {
+  pname = "sphinx-tabs";
+  version = "3.2.0";
+
+  src = fetchPypi {
+    inherit pname version;
+    sha256 = "sha256:1970aahi6sa7c37cpz8nwgdb2xzf21rk6ykdd1m6w9wvxla7j4rk";
+  };
+
+  propagatedBuildInputs = [
+    sphinx
+  ];
+
+  doCheck = false;
+
+  pythonImportsCheck = [ "sphinx_tabs" ];
+
+  meta = with lib; {
+    description = "Create tabbed content in Sphinx documentation when building HTML";
+    homepage = "https://sphinx-tabs.readthedocs.io";
+    license = licenses.mit;
+  };
+}

requirements.txt

@@ -1 +1,3 @@
-docutils==0.17.1
+docutils==0.17.1
+sphinx-tabs
+sphinx-copybutton

schema_cache.rst

@@ -41,9 +41,15 @@ Stale Foreign Key Relationships
 
 Suppose you add a ``cities`` table to your database and define a foreign key that references an existing ``countries`` table. Then, you make a request to get the ``cities`` and their belonging ``countries``.
 
-.. code-block:: http
+.. tabs::
 
-  GET /cities?select=name,country:countries(id,name) HTTP/1.1
+  .. code-tab:: http
+
+    GET /cities?select=name,country:countries(id,name) HTTP/1.1
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/cities?select=name,country:countries(id,name)"
 
 The result will be an error:
 
@@ -70,9 +76,15 @@ The same issue will occur on newly created functions on a running PostgREST.
    SELECT num + 1;
   $$ LANGUAGE SQL IMMUTABLE;
 
-.. code-block:: http
+.. tabs::
 
-  GET /rpc/plus_one?num=1 HTTP/1.1
+  .. code-tab:: http
+
+    GET /rpc/plus_one?num=1 HTTP/1.1
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/rpc/plus_one?num=1"
 
 .. code-block:: json