diff --git a/CHANGELOG.md b/CHANGELOG.md index 9627f4f8b6..74a6edb6fe 100644 --- 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 index 602ef678fc..0839457dc7 100644 --- 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 index ab279ba1f9..af3c9f3c27 100644 --- 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 index 14775581e2..73cadb26b0 100644 --- 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 index 6baa61aabf..d0c249ad6a 100644 --- 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 index 0eddfe956a..054dc249f3 100644 --- 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 index 0c32b87543..145ad2dc3b 100644 --- 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 new file mode 100644 index 0000000000..6e78bdb385 --- /dev/null +++ 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 index 62e031da99..f177c4f093 100644 --- 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 new file mode 100644 index 0000000000..212f19cde9 Binary files /dev/null and b/static/code-build-dark.png differ diff --git a/static/cybertec-dark.svg b/static/cybertec-dark.svg new file mode 100644 index 0000000000..bcd1f1bd84 --- /dev/null +++ b/static/cybertec-dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/neon-dark.jpg b/static/neon-dark.jpg new file mode 100644 index 0000000000..816668d62b Binary files /dev/null and b/static/neon-dark.jpg differ diff --git a/static/supabase-dark.png b/static/supabase-dark.png new file mode 100644 index 0000000000..dfb977303a Binary files /dev/null and b/static/supabase-dark.png differ