docs: add dark mode

- Uses sphinx-rtd-dark-mode for sphinx-rtd-theme - Adds dark mode logos for sponsors
PostgREST · Apr 10, 2024 · 70396d3 · 70396d3
1 parent c913681
commit 70396d3
Show file tree

Hide file tree

Showing 13 changed files with 155 additions and 17 deletions.
diff --git a/CHANGELOG.md b/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

diff --git a/docs/_static/css/custom.css b/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;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -32,6 +32,7 @@
  "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 @@ def setup(app):
 # 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"

diff --git a/docs/explanations/schema_isolation.rst b/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
diff --git a/docs/index.rst b/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/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
- :width: 13em
+ .. 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
 
 |
 

diff --git a/docs/requirements.txt b/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

diff --git a/docs/tutorials/tut0.rst b/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.
 

diff --git a/nix/docs-extensions/sphinx-rtd-dark-mode.nix b/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;
+ };
+}
diff --git a/nix/tools/docs.nix b/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 ]; }))
  ];

diff --git a/static/code-build-dark.png b/static/code-build-dark.png
diff --git a/static/cybertec-dark.svg b/static/cybertec-dark.svg
diff --git a/static/neon-dark.jpg b/static/neon-dark.jpg
diff --git a/static/supabase-dark.png b/static/supabase-dark.png