From 1ffbf767cc9378c795224f45fe7136a738e11afc Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Mon, 6 May 2024 19:03:50 +0100 Subject: [PATCH] Add release information to various customisation knobs This makes it easier for users to understand whether a feature they're looking at would be supported by the version of Furo they're using. Also reword a few things since I'm already going through and tweaking lots of these documents. --- docs/customisation/announcement.md | 4 +++ docs/customisation/colors.md | 4 +++ docs/customisation/edit-button.md | 8 +++++ docs/customisation/fonts.md | 15 +++++++-- docs/customisation/footer.md | 4 +++ docs/customisation/index.md | 40 +++++++++++++++++++++-- docs/customisation/logo.md | 8 +++++ docs/customisation/sidebar.md | 4 +++ docs/customisation/toc.md | 4 +++ docs/customisation/top-of-page-buttons.md | 22 ++++++++++++- 10 files changed, 108 insertions(+), 5 deletions(-) diff --git a/docs/customisation/announcement.md b/docs/customisation/announcement.md index c39db9970..672331d5c 100644 --- a/docs/customisation/announcement.md +++ b/docs/customisation/announcement.md @@ -1,5 +1,9 @@ # Adding an announcement banner +```{versionadded} 2020.12.28.beta22 + +``` + Furo makes it fairly straightforward to add a site-wide announcement (AKA top banner). The announcement is added to the top of all pages on the website. This is done by setting `announcement` key in [`html_theme_options`][sphinx-html_theme_options] in your `conf.py` file. The value of this key is HTML, which is included as-is into the page. diff --git a/docs/customisation/colors.md b/docs/customisation/colors.md index 05c14a9dd..87a1e4eb7 100644 --- a/docs/customisation/colors.md +++ b/docs/customisation/colors.md @@ -1,5 +1,9 @@ # Changing colors +```{versionadded} 2020.11.14.beta16 + +``` + Furo allows customising colors to fit your brand's identity, by using CSS variables. These can be declared directly in [`html_theme_options`][sphinx-html_theme_options], in your `conf.py`. ## How light and dark mode work diff --git a/docs/customisation/edit-button.md b/docs/customisation/edit-button.md index 368a7e5cb..ca72e84fb 100644 --- a/docs/customisation/edit-button.md +++ b/docs/customisation/edit-button.md @@ -4,4 +4,12 @@ orphan: true # Adding an edit button +```{versionadded} 2022.02.14 + +``` + +```{versionchanged} 2024.05.06 +View button support was added, which required providing a more general configuration mechanism. +``` + This page has been replaced with {doc}`./top-of-page-buttons`. diff --git a/docs/customisation/fonts.md b/docs/customisation/fonts.md index aebaf4b74..18a83396a 100644 --- a/docs/customisation/fonts.md +++ b/docs/customisation/fonts.md @@ -1,18 +1,29 @@ # Changing fonts +```{versionadded} 2020.08.14.beta5 + +``` + +```{versionchanged} 2024.04.27 +Add `font-stack--headings`. +``` + Furo makes it fairly straightforward to change the fonts across the entire page. -This is done by changing the values of the relevant CSS variables: `font-stack` (for regular text) and `font-stack--monospace` (for code blocks and inline code). This can be done using Furo's [mechanism for setting CSS variables](css-variables) -- specifically by setting them as the fonts for the light mode (which is inherited by the dark mode). +This is done by changing the values of the relevant CSS variables: `font-stack` (for regular text), `font-stack--monospace` (for code blocks and inline code) and `font-stack--headings` (for headings). This can be done using Furo's [mechanism for setting CSS variables](css-variables) -- specifically by setting them as the fonts for the light mode (which is inherited by the dark mode). ```py html_theme_options = { "light_css_variables": { "font-stack": "Arial, sans-serif", "font-stack--monospace": "Courier, monospace", + "font-stack--headings": "Georgia, serif", }, } ``` ```{note} -It is strongly recommended to not change the fonts unless there is a strong reason (such as brand identity) since Furo's default fonts are carefully selected to look good across all major platforms. +It is strongly recommended to not change the fonts unless there is a strong reason (such as brand identity). + +Furo's default fonts are carefully selected to look good across all major platforms without requiring additional web font downloads, enabling faster page loads and higher quality text presentation. ``` diff --git a/docs/customisation/footer.md b/docs/customisation/footer.md index 33c551bc3..ea8964503 100644 --- a/docs/customisation/footer.md +++ b/docs/customisation/footer.md @@ -1,5 +1,9 @@ # Changing footer icons +```{versionadded} 2022.02.14 + +``` + Furo allows customising the icons that are presented in the page footer. These icons can be used to link to relevant resources for your project and documentation. ```{admonition} Unstable, seeking feedback diff --git a/docs/customisation/index.md b/docs/customisation/index.md index 47fe24ba0..ff3aa4efb 100644 --- a/docs/customisation/index.md +++ b/docs/customisation/index.md @@ -30,7 +30,15 @@ Note that only the configuration options listed here are supported (not the ones (css-variables)= -### `light_css_variables`/`dark_css_variables` +### `light_css_variables` / `dark_css_variables` + +```{versionadded} 2020.08.14.beta5 + +``` + +```{versionchanged} 2020.11.01.beta14 +Support for dark mode involved replacing `css_variables` with `light_css_variables` / `dark_css_variables`. +``` Furo makes extensive use of [CSS variables][css-variables]. These can be overridden by the user and are used for stylizing nearly all elements of the documentation. {doc}`colors` contains important details of how these variables are used. @@ -54,6 +62,10 @@ Typos in the `*_css_variables` dictionary are silently ignored, and do not raise ### `sidebar_hide_name` +```{versionadded} 2020.08.14.beta5 + +``` + Controls whether you see the project's name in the sidebar of the documentation. This is useful when you only want to show your documentation's logo in the sidebar. The default is `False`. ```python @@ -64,6 +76,10 @@ html_theme_options = { ### `navigation_with_keys` +```{versionadded} 2020.11.01.beta14 +This is functionality [supported by Sphinx's `basic` theme](https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes). +``` + Controls whether the user can navigate the documentation using the keyboard’s left and right arrows. The default is `False`. ```python @@ -76,6 +92,10 @@ html_theme_options = { ### `top_of_page_button` +```{versionadded} 2022.06.04 + +``` + ```{deprecated} 2024.05.06 This will be removed after 2024-11-01. Use `top_of_page_buttons` instead. ``` @@ -92,6 +112,10 @@ html_theme_options = { ### `top_of_page_buttons` +```{versionadded} 2024.05.06 + +``` + Controls which buttons are shown on the top of the page. This is a list which can be empty or contain one-or-more of the following values: - `"edit"` @@ -105,10 +129,18 @@ html_theme_options = { ### `announcement` +```{versionadded} 2020.12.28.beta22 + +``` + Add a site-wide announcement, to the top of every page when set. See {doc}`./announcement` for the details. ### `footer_icons` +```{versionadded} 2022.02.14 + +``` + Changes the icons presented in the site footer. See {doc}`./footer` for the details. ## Page specific tweaks @@ -117,7 +149,11 @@ Changes the icons presented in the site footer. See {doc}`./footer` for the deta ### `hide-toc` -The “Contents” sidebar is automatically hidden for any pages that don’t have any inner headings. It is possible to hide it even when a page has inner headings, by setting `hide-toc` at the page level. See {doc}`./toc` for an example. +```{versionadded} 2020.08.14.beta5 + +``` + +The "Contents" sidebar is automatically hidden for any pages that don’t have any inner headings. It is possible to hide it even when a page has inner headings, by setting `hide-toc` at the page level. See {doc}`./toc` for an example. ## Custom CSS files diff --git a/docs/customisation/logo.md b/docs/customisation/logo.md index 69db42d3a..fed5c43bc 100644 --- a/docs/customisation/logo.md +++ b/docs/customisation/logo.md @@ -1,5 +1,13 @@ # Adding a logo +```{versionadded} 2020.08.14.beta5 + +``` + +```{versionchanged} 2020.11.10.beta15 +Support for different logos for light and dark mode. +``` + Logos are a point of recognition and an important part of branding. Furo supports adding your project's logo at the top of the navigational (left) sidebar, like most other Sphinx themes. ## Same logo for light and dark mode diff --git a/docs/customisation/sidebar.md b/docs/customisation/sidebar.md index f786c137a..e11637c32 100644 --- a/docs/customisation/sidebar.md +++ b/docs/customisation/sidebar.md @@ -1,5 +1,9 @@ # Changing sidebar elements +```{versionadded} 2020.11.15.beta17 + +``` + Furo supports customising the elements that show up in the navigational sidebar (left). This is to provide documentation authors who are willing to work with HTML/CSS to change and tweak how the sidebar looks. ```{admonition} Unstable diff --git a/docs/customisation/toc.md b/docs/customisation/toc.md index aecac5982..da2f51484 100644 --- a/docs/customisation/toc.md +++ b/docs/customisation/toc.md @@ -1,5 +1,9 @@ # Hiding Contents sidebar +```{versionadded} 2020.08.14.beta5 + +``` + Furo supports hiding the "Contents" sidebar (right), and does so automatically for any pages that don't have any inner headings. To explicitly hide it on a specific page, `hide-toc` can be set in the [File-Wide metadata][sphinx-file-wide-metadata] for that page. diff --git a/docs/customisation/top-of-page-buttons.md b/docs/customisation/top-of-page-buttons.md index d5dfb7315..f18e99dd1 100644 --- a/docs/customisation/top-of-page-buttons.md +++ b/docs/customisation/top-of-page-buttons.md @@ -1,4 +1,8 @@ -# Adding source code buttons +# Changing buttons on page + +```{versionadded} 2022.02.14 +Support for "edit this page" link. +``` ```{versionadded} 2024.05.06 Support for "view this page" link. @@ -25,7 +29,11 @@ This model supports github.com, gitlab.com and bitbucket.org as domain names for ## With arbitrary URLs ```{versionadded} 2022.09.29 +`source_edit_link` +``` +```{versionadded} 2024.05.06 +`source_view_link` ``` Use arbitrary URLs for the view/edit buttons, by setting the following keys in [`html_theme_options`][sphinx-html_theme_options]: @@ -49,6 +57,10 @@ If [`html_show_sourcelink`](https://www.sphinx-doc.org/en/master/usage/configura ## Read the Docs support +```{versionadded} 2022.02.14 + +``` + ```{note} This feature is only available for projects hosted on GitHub. ``` @@ -74,6 +86,14 @@ html_show_sourcelink = False ### Disabling on Read the Docs +```{versionadded} 2022.06.04 + +``` + +```{versionchanged} 2024.05.06 +`top_of_page_buttons` replaces the singular `top_of_page_button`. +``` + If you wish to disable these default buttons, use {ref}`top_of_page_buttons` and set it to `[]`. [sphinx-html_theme_options]: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_theme_options