Skip to content

Commit

Permalink
Add release information to various customisation knobs
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
pradyunsg committed May 6, 2024
1 parent 2c386b9 commit 1ffbf76
Show file tree
Hide file tree
Showing 10 changed files with 108 additions and 5 deletions.
4 changes: 4 additions & 0 deletions docs/customisation/announcement.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
4 changes: 4 additions & 0 deletions docs/customisation/colors.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
8 changes: 8 additions & 0 deletions docs/customisation/edit-button.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
15 changes: 13 additions & 2 deletions docs/customisation/fonts.md
Original file line number Diff line number Diff line change
@@ -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.
```
4 changes: 4 additions & 0 deletions docs/customisation/footer.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
40 changes: 38 additions & 2 deletions docs/customisation/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
```
Expand All @@ -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"`
Expand All @@ -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
Expand All @@ -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

Expand Down
8 changes: 8 additions & 0 deletions docs/customisation/logo.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
4 changes: 4 additions & 0 deletions docs/customisation/sidebar.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
4 changes: 4 additions & 0 deletions docs/customisation/toc.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
22 changes: 21 additions & 1 deletion docs/customisation/top-of-page-buttons.md
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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]:
Expand All @@ -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.
```
Expand All @@ -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

0 comments on commit 1ffbf76

Please sign in to comment.