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

diff --git a/CHANGES.md b/CHANGES.md
index 83117e65dc49c5b885ee5af3dd28435e8c4a8979..4f4c6a2ffc7864a4995e4b994d9ee681f4cdc9dc 100644 (file)
--- 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 (file)
index eacd69c..0000000
--- 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 55d0fa99dc6c2ce290fe0c7ec9b1b31ae7590bf5..2801e0eed19bb177e14c65fdf288fd6af6f14e56 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -115,29 +115,8 @@ myst_disable_syntax = [
 # 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 94a978d826f397f58aa0ba004def5c3f609cf335..1ebdcd9530d7a938922e413437f03dae3127d2a7 100644 (file)
--- 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 1515697f5569afcab35f8ad3b07cbd8f5f27690b..6818c03cfe9b0c7ff213c1521c4c178db12b725f 100644 (file)
--- 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 02874d3c255f332949d4473822c7449d6b9aecee..01fea693f0721141089a7d2bfaeefb46fa3f3429 100644 (file)
--- 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