From d24bc4364c6ef2337875be1a5b4e0851adaaf0f6 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Fri, 21 Jan 2022 18:00:13 -0500
Subject: [PATCH] Switch to Furo (#2793)

- Add Furo dependency to docs/requirements.txt
- Drop a fair bit of theme configuration
- Fix the toctree declarations in index.rst
- Move stuff around as Furo isn't 100% compatible with Alabaster

Furo was chosen as it provides excellent mobile support, user
controllable light/dark theming, and is overall easier to read
---
 CHANGES.md              |  2 ++
 docs/_static/custom.css | 44 -----------------------------------------
 docs/conf.py            | 25 ++---------------------
 docs/faq.md             |  1 +
 docs/index.rst          | 13 ++++++++----
 docs/requirements.txt   |  1 +
 6 files changed, 15 insertions(+), 71 deletions(-)
 delete mode 100644 docs/_static/custom.css

diff --git a/CHANGES.md b/CHANGES.md
index 83117e65dc4..4f4c6a2ffc7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -53,6 +53,8 @@
 ### Documentation
 
 - Change protocol in pip installation instructions to `https://` (#2761)
+- Change HTML theme to Furo primarily for its responsive design and mobile support
+  (#2793)
 
 ## 21.12b0
 
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
deleted file mode 100644
index eacd69c15a0..00000000000
--- a/docs/_static/custom.css
+++ /dev/null
@@ -1,44 +0,0 @@
-/* Make the sidebar scrollable. Fixes https://github.com/psf/black/issues/990 */
-div.sphinxsidebar {
-  max-height: calc(100% - 18px);
-  overflow-y: auto;
-}
-
-/* Hide scrollbar for Chrome, Safari and Opera */
-div.sphinxsidebar::-webkit-scrollbar {
-  display: none;
-}
-
-/* Hide scrollbar for IE 6, 7 and 8 */
-@media \0screen\, screen\9 {
-  div.sphinxsidebar {
-    -ms-overflow-style: none;
-  }
-}
-
-/* Hide scrollbar for IE 9 and 10 */
-/* backslash-9 removes ie11+ & old Safari 4 */
-@media screen and (min-width: 0\0) {
-  div.sphinxsidebar {
-    -ms-overflow-style: none\9;
-  }
-}
-
-/* Hide scrollbar for IE 11 and up */
-_:-ms-fullscreen,
-:root div.sphinxsidebar {
-  -ms-overflow-style: none;
-}
-
-/* Hide scrollbar for Edge */
-@supports (-ms-ime-align: auto) {
-  div.sphinxsidebar {
-    -ms-overflow-style: none;
-  }
-}
-
-/* Nicer style for local document toc */
-.contents.topic {
-  background: none;
-  border: none;
-}
diff --git a/docs/conf.py b/docs/conf.py
index 55d0fa99dc6..2801e0eed19 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -115,29 +115,8 @@ def make_pypi_svg(version: str) -> None:
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
-
-html_sidebars = {
-    "**": [
-        "about.html",
-        "navigation.html",
-        "relations.html",
-        "searchbox.html",
-    ]
-}
-
-html_theme_options = {
-    "show_related": False,
-    "description": "“Any color you like.”",
-    "github_button": True,
-    "github_user": "psf",
-    "github_repo": "black",
-    "github_type": "star",
-    "show_powered_by": True,
-    "fixed_sidebar": True,
-    "logo": "logo2.png",
-}
-
+html_theme = "furo"
+html_logo = "_static/logo2-readme.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
diff --git a/docs/faq.md b/docs/faq.md
index 94a978d826f..1ebdcd9530d 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -5,6 +5,7 @@ The most common questions and issues users face are aggregated to this FAQ.
 ```{contents}
 :local:
 :backlinks: none
+:class: this-will-duplicate-information-and-it-is-still-useful-here
 ```
 
 ## Does Black have an API?
diff --git a/docs/index.rst b/docs/index.rst
index 1515697f556..6818c03cfe9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -4,6 +4,8 @@
 The uncompromising code formatter
 =================================
 
+    “Any color you like.”
+
 By using *Black*, you agree to cede control over minutiae of
 hand-formatting. In return, *Black* gives you speed, determinism, and
 freedom from `pycodestyle` nagging about formatting. You will save time
@@ -99,6 +101,7 @@ Contents
 .. toctree::
    :maxdepth: 3
    :includehidden:
+   :caption: User Guide
 
    getting_started
    usage_and_configuration/index
@@ -107,8 +110,9 @@ Contents
    faq
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :includehidden:
+   :caption: Development
 
    contributing/index
    change_log
@@ -116,10 +120,11 @@ Contents
 
 .. toctree::
    :hidden:
+   :caption: Project Links
 
-   GitHub ↪ <https://github.com/psf/black>
-   PyPI ↪ <https://pypi.org/project/black>
-   Chat ↪ <https://discord.gg/RtVdv86PrH>
+   GitHub <https://github.com/psf/black>
+   PyPI <https://pypi.org/project/black>
+   Chat <https://discord.gg/RtVdv86PrH>
 
 Indices and tables
 ==================
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 02874d3c255..01fea693f07 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -4,3 +4,4 @@ myst-parser==0.16.1
 Sphinx==4.4.0
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.4.0
+furo==2022.1.2