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 83117e6..4f4c6a2 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 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 55d0fa9..2801e0e 100644 --- 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 94a978d..1ebdcd9 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 1515697..6818c03 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 ↪ - PyPI ↪ - Chat ↪ + GitHub + PyPI + Chat Indices and tables ================== diff --git a/docs/requirements.txt b/docs/requirements.txt index 02874d3..01fea69 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 -- 2.39.5