docs: add dark mode

- Uses sphinx-rtd-dark-mode for sphinx-rtd-theme
- Adds dark mode logos for sponsors

CHANGELOG.md

@@ -32,6 +32,10 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
  - `Prefer: params=single-object` is deprecated. Use [a function with a single unnamed JSON parameter](https://postgrest.org/en/latest/references/api/stored_procedures.html#s-proc-single-json) instead. - @steve-chavez
 
+### Documentation
+
+ - #3289, Add dark mode. Can be toggled by a button in the bottom right corner. - @laurenceisla
+
 ## [12.0.2] - 2023-12-20
 
 ### Fixed

docs/_static/css/custom.css

@@ -28,6 +28,7 @@ div.line-block {
 
 #sponsors img{
   margin: 10px;
+  width: 13em; /* ".. image::" does not apply width properly to SVGs */
 }
 
 #thanks{
@@ -93,3 +94,58 @@ div.line-block {
 #api span.caption-text {
     display: none;
 }
+
+/* Tweaks for dark mode from extension: sphinx-rtd-dark-theme */
+
+html[data-theme="dark"] .highlight {
+  background-color: #17181c !important;
+}
+
+html[data-theme="dark"] .sphinx-tabs-tab {
+  color: var(--dark-link-color);
+}
+
+html[data-theme="dark"] .sphinx-tabs-panel {
+  border: 1px solid #404040;
+  border-top: 0;
+  background: #141414;
+}
+
+html[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] {
+  border: 1px solid #404040;
+  border-bottom: 1px solid #141414;
+  background-color: #141414;
+}
+
+html[data-theme="dark"] [role="tablist"] {
+  border-bottom: 1px solid #404040;
+}
+
+html[data-theme="dark"] .btn-neutral {
+  color: white !important;
+}
+
+html[data-theme="dark"] .img-dark {
+  display: inline;
+}
+
+html:not([data-theme="dark"]) .img-dark {
+  display: none;
+}
+
+html[data-theme="dark"] .img-light {
+  display: none;
+}
+
+html:not([data-theme="dark"]) .img-light {
+  display: inline;
+}
+
+html[data-theme="dark"] .img-translucent img {
+  background-color: #cccccc;
+}
+
+.img-translucent img {
+  transition: background-color 0.3s;
+  margin-bottom: 24px;
+}

docs/conf.py

@@ -32,6 +32,7 @@ extensions = [
     "sphinx_tabs.tabs",
     "sphinx_copybutton",
     "sphinxext.opengraph",
+    "sphinx_rtd_dark_mode",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -301,6 +302,9 @@ linkcheck_ignore = [r"https://stackoverflow.com/"]
 # sphinx-tabs configuration
 sphinx_tabs_disable_tab_closing = True
 
+# sphinx_rtd_dark_mode configuration
+default_dark_mode = False
+
 # sphinxext-opengraph configuration
 
 ogp_image = "_images/logo.png"

docs/explanations/schema_isolation.rst

@@ -12,4 +12,6 @@ A PostgREST instance exposes all the tables, views, and functions of a single `P
 It is recommended that you don't expose tables on your API schema. Instead expose views and functions which insulate the internal details from the outside world.
 This allows you to change the internals of your schema and maintain backwards compatibility. It also keeps your code easier to refactor, and provides a natural way to do API versioning.
 
-.. image:: ../_static/db.png
+.. container:: img-translucent
+
+  .. image:: ../_static/db.png

docs/index.rst

@@ -34,38 +34,59 @@ Sponsors
 
 .. container:: image-container
 
-  .. image:: ../static/cybertec-new.png
-    :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest
-    :width:  13em
+  .. container:: img-dark
+
+    .. image:: ../static/cybertec-dark.svg
+      :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest
+
+  .. container:: img-light
+
+    .. image:: ../static/cybertec-new.png
+      :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest
 
   .. image:: ../static/gnuhost.png
     :target: https://gnuhost.eu/?utm_source=sponsor&utm_campaign=postgrest
-    :width:  13em
 
-  .. image:: ../static/neon.jpg
-    :target: https://neon.tech/?utm_source=sponsor&utm_campaign=postgrest
-    :width:  13em
+  .. container:: img-dark
+
+    .. image:: ../static/neon-dark.jpg
+      :target: https://neon.tech/?utm_source=sponsor&utm_campaign=postgrest
+
+  .. container:: img-light
+
+    .. image:: ../static/neon.jpg
+      :target: https://neon.tech/?utm_source=sponsor&utm_campaign=postgrest
 
   |
 
-  .. image:: ../static/code-build.webp
-    :target: https://code.build/?utm_source=sponsor&utm_campaign=postgrest
-    :width:  13em
+  .. container:: img-dark
 
-  .. 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/code-build-dark.png
+      :target: https://code.build/?utm_source=sponsor&utm_campaign=postgrest
+
+  .. container:: img-light
+
+    .. image:: ../static/code-build.webp
+      :target: https://code.build/?utm_source=sponsor&utm_campaign=postgrest
+
+  .. container:: img-dark
+
+    .. image:: ../static/supabase-dark.png
+      :target: https://supabase.com/?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage
+
+  .. container:: img-light
+
+    .. 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
 
   .. image:: ../static/tembo.png
     :target: https://tembo.io/?utm_source=sponsor&utm_campaign=postgrest
-    :width:  13em
 
   .. The static/empty.png(created with `convert -size 320x95 xc:#fcfcfc empty.png`) is an ugly workaround
      to create space and center the logos. It's not easy to layout with restructuredText.
 
   .. .. image:: _static/empty.png
        :target: #sponsors
-       :width:  13em
 
 |
 

docs/requirements.txt

@@ -2,6 +2,7 @@ docutils==0.20.1
 sphinx-copybutton
 sphinx-intl
 sphinx-rtd-theme>=0.5.1
+sphinx-rtd-dark-mode>=1.3.0
 sphinx-tabs>=3.2.0
 sphinx>=5.0.2
 sphinxext-opengraph==0.9.1

docs/tutorials/tut0.rst

@@ -9,7 +9,9 @@ Welcome to PostgREST! In this pre-tutorial we're going to get things running so
 
 PostgREST is a standalone web server which turns a PostgreSQL database into a RESTful API. It serves an API that is customized based on the structure of the underlying database.
 
-.. image:: ../_static/tuts/tut0-request-flow.png
+.. container:: img-translucent
+
+  .. image:: ../_static/tuts/tut0-request-flow.png
 
 To make an API we'll simply be building a database. All the endpoints and permissions come from database objects like tables, views, roles, and functions. These tutorials will cover a number of common scenarios and how to model them in the database.
 

nix/docs-extensions/sphinx-rtd-dark-mode.nix

@@ -0,0 +1,46 @@
+{ buildPythonPackage
+, fetchFromGitHub
+, lib
+, nose
+, sphinx
+, sphinx-rtd-theme
+}:
+
+buildPythonPackage rec {
+  pname = "sphinx-rtd-dark-mode";
+  version = "1.3.0";
+  format = "setuptools";
+
+  src = fetchFromGitHub {
+    owner = "MrDogeBro";
+    repo = "sphinx_rtd_dark_mode";
+    rev = "refs/tags/v${version}";
+    hash = "sha256-N5KG2Wqn9wfGNY3VH4FnBce1aZUbnvVmwD10Loe0Qn4=";
+  };
+
+  propagatedBuildInputs = [
+    sphinx-rtd-theme
+  ];
+
+  nativeCheckInputs = [
+    nose
+    sphinx
+  ];
+
+  checkPhase = ''
+    runHook preCheck
+    nosetests tests
+    runHook postCheck
+  '';
+
+  pythonImportsCheck = [
+    "sphinx_rtd_dark_mode"
+  ];
+
+  meta = with lib; {
+    description = "Adds a toggleable dark mode to the Read the Docs theme for Sphinx.";
+    homepage = "https://github.com/MrDogeBro/sphinx_rtd_dark_mode";
+    changelog = "https://github.com/MrDogeBro/sphinx_rtd_dark_mode/releases/tag/v${version}";
+    license = licenses.mit;
+  };
+}

nix/tools/docs.nix

@@ -17,6 +17,7 @@ let
     ps.sphinx-tabs
     ps.sphinx-copybutton
     ps.sphinxext-opengraph
+    (ps.callPackage ../docs-extensions/sphinx-rtd-dark-mode.nix { })
     # TODO: Remove override once new sphinx-intl version (> 2.1.0) is released and available in nixpkgs
     (ps.sphinx-intl.overrideAttrs (drv: { nativeBuildInputs = drv.nativeBuildInputs ++ [ ps.six ]; }))
   ];