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.
pradyunsg · May 6, 2024 · 1ffbf76 · 1ffbf76
1 parent 2c386b9
commit 1ffbf76
Show file tree

Hide file tree

Showing 10 changed files with 108 additions and 5 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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