Switch the manual theme to Furo #104735

Aaron Carlisle · 2024-03-15T03:02:05+01:00

Aaron Carlisle commented

2024-03-15 03:02:05 +01:00

Since moving from the Wiki we have used the sphinx_rtd_theme which has worked well but has become a little dated and has had slow development. This changes to use "Furo" instead.

Furo is a lightweight theme that is responsive and has native dark mode support.

Dark mode is one of the major enhancements but this change also brings:

Content is slightly larger making text and images easier to view
Site navigation and page navigation is split into two navigation trees. The site navigation is on the left and page on the right if the page has multiple headings.
Return to top button
Content is centered on the screen which helps with wide monitors
No more breadcrumbs
Remove google analytics

So far the caveat that I have noticed with this is slower compile times and larger pages, this is due to the better sidebar navigation.

This change also brings a lot of simplifications to customizations that we made to the sphinx_rtd_theme. There is still likely room for improvement in the future.

Since moving from the Wiki we have used the `sphinx_rtd_theme` which has worked well but has become a little dated and has had slow development. This changes to use "Furo" instead. [Furo](https://github.com/pradyunsg/furo) is a lightweight theme that is responsive and has native dark mode support. Dark mode is one of the major enhancements but this change also brings: - Content is slightly larger making text and images easier to view - Site navigation and page navigation is split into two navigation trees. The site navigation is on the left and page on the right if the page has multiple headings. - Return to top button - Content is centered on the screen which helps with wide monitors - No more breadcrumbs - Remove google analytics So far the caveat that I have noticed with this is slower compile times and larger pages, this is due to the better sidebar navigation. This change also brings a lot of simplifications to customizations that we made to the `sphinx_rtd_theme`. There is still likely room for improvement in the future.

❤️ 3

Aaron Carlisle requested review from Brecht Van Lommel 2024-03-15 03:05:23 +01:00

Aaron Carlisle requested review from Pablo Vazquez 2024-03-15 03:05:23 +01:00

Aaron Carlisle requested review from Campbell Barton 2024-03-15 03:05:24 +01:00

Aaron Carlisle commented

2024-03-15 03:07:22 +01:00

Ive requested review from different people for different purposes:

@brecht evaluate the burden of increased build times on build-bot
@pablovazquez Review of front end changes
@ideasman42 For historical interest in the project / python side

Ive requested review from different people for different purposes: @brecht evaluate the burden of increased build times on build-bot @pablovazquez Review of front end changes @ideasman42 For historical interest in the project / python side

Aaron Carlisle commented

2024-03-15 03:09:06 +01:00

@blender-bot package

Blender Bot commented

2024-03-15 03:09:07 +01:00

Package not supported for blender/blender-manual. See documentation for details.

Package not supported for blender/blender-manual. See [documentation](https://projects.blender.org/infrastructure/blender-bot/src/branch/main/README.md) for details.

Aaron Carlisle commented

2024-03-15 03:12:06 +01:00

@blender-bot build

Campbell Barton approved these changes 2024-03-15 04:10:55 +01:00

Dismissed

Campbell Barton left a comment

Looks good, only one minor issue noted.

The reference box seems a little low contrast compared with the background (they're used in many places, to pick one example: interface/window_system/areas.html).

Checked Blender's Python API docs and they also look good.

Looks good, only one minor issue noted. The reference box seems a little low contrast compared with the background (they're used in many places, to pick one example: `interface/window_system/areas.html`). Checked Blender's Python API docs and they also look good.

Aaron Carlisle commented

2024-03-15 04:29:22 +01:00

Kinda agree with the ref boxes, I'll look into adjusting the colors some more.

I plan to make a PR for the API once this PR is accepted.

Kinda agree with the ref boxes, I'll look into adjusting the colors some more. I plan to make a PR for the API once this PR is accepted.

👍 1

Campbell Barton commented

2024-03-15 04:31:38 +01:00

Noticed another issue with shortcuts:

Alt-G is displayed as Alt - G for e.g..

See: animation/constraints/relationship/follow_path.html

Noticed another issue with shortcuts: `Alt-G` is displayed as `Alt` - `G` for e.g.. See: `animation/constraints/relationship/follow_path.html`

Aaron Carlisle commented

2024-03-15 04:47:35 +01:00

Noticed another issue with shortcuts:

Alt-G is displayed as Alt - G for e.g..

See: animation/constraints/relationship/follow_path.html

This is intentional by the theme, I have no preference either way.

> Noticed another issue with shortcuts: > > `Alt-G` is displayed as `Alt` - `G` for e.g.. > > See: `animation/constraints/relationship/follow_path.html` This is intentional by the theme, I have no preference either way.

Campbell Barton commented

2024-03-15 10:07:22 +01:00

Having them separate doesn't read so well, especially with multiple key shortcuts separated by commas.

screenshot.webm

18 KiB

screenshot_before.webm

16 KiB

screenshot.webm

20 KiB

👍 1

Brecht Van Lommel commented

2024-03-15 16:05:24 +01:00

Build times on the buildbot should not be a problem.

Overall it looks nice. Personally not a big fan of the extra font size on large screens, and I would tweak the h1..h6 text to be a bit smaller, not pure black and maybe increase margins. Compared to the old the theme or the developer docs it looks quite busy to me. But that's personal opinion.

Old	New

Build times on the buildbot should not be a problem. Overall it looks nice. Personally not a big fan of the [extra font size on large screens](https://github.com/pradyunsg/furo/discussions/369), and I would tweak the h1..h6 text to be a bit smaller, not pure black and maybe increase margins. Compared to the old the theme or the developer docs it looks quite busy to me. But that's personal opinion. |Old|New| |-|-| |![old.png](/attachments/d07950f4-242e-4d41-8c12-58afc3801293)|![new.png](/attachments/1c2838f8-b4b9-4dd1-9422-611c79969d49)|

old.png

248 KiB

new.png

262 KiB

👍 1

Aaron Carlisle commented

2024-03-17 21:22:23 +01:00

@ideasman42 @brecht your review points have been addressed with the exception Brecht's comments on font sizes on larger screens and the body text color.

I think those are a little bit more subjective, so it would be nice to hear from others before making those adjustments.

@ideasman42 @brecht your review points have been addressed with the exception Brecht's comments on font sizes on larger screens and the body text color. I think those are a little bit more subjective, so it would be nice to hear from others before making those adjustments.

Aaron Carlisle commented

2024-03-17 21:27:13 +01:00

On a side note, I have kept the google analytics but I have noticed some Blender sites have been using https://analytics.blender.org is that service still in testing?

Perhaps @fsiddi can answer this question. I can switch the manual to use that service if desired.

On a side note, I have kept the google analytics but I have noticed some Blender sites have been using https://analytics.blender.org is that service still in testing? Perhaps @fsiddi can answer this question. I can switch the manual to use that service if desired.

Campbell Barton commented

2024-03-17 23:40:09 +01:00

Checking again, noticed another issue.

For the page: advanced/limits.html.

Before:

After:

This seems like a bug in the theme since those values use a field-list, unlike table widths which are adjustable:

:24 fps: 12 hours, 8 minutes.
:25 fps: 11 hours, 39 minutes.
:30 fps: 9 hours, 42 minutes.
:60 fps: 4 hours, 51 minutes.

Checking again, noticed another issue. For the page: `advanced/limits.html`. Before: ![screenshot.jpg](/attachments/8bfe9d1b-3965-4215-bd78-581c5311f955) After: ![screenshot.jpg](/attachments/e65069a1-a68a-4dea-a9a6-15dd77f413ad) ---- This seems like a bug in the theme since those values use a field-list, unlike table widths which are adjustable: ``` :24 fps: 12 hours, 8 minutes. :25 fps: 11 hours, 39 minutes. :30 fps: 9 hours, 42 minutes. :60 fps: 4 hours, 51 minutes. ```

screenshot.jpg

69 KiB

screenshot.jpg

65 KiB

Brecht Van Lommel commented

2024-03-18 01:23:26 +01:00

Thanks for the changes, the titles look so much better now.

Two minor comments.

I suggest to make the caption font size a bit smaller than other text, as it was before and is quite common I think. It helps make it stand apart from the rest of the text, otherwise you can confuse it for a regular paragraph in some cases.

On various compositing index pages I noticed there is too much spacing. The solution may be to edit those pages to remove the horizontal lines, they seem to be the only index pages using them like this.

Old	New

Thanks for the changes, the titles look so much better now. Two minor comments. I suggest to make the caption font size a bit smaller than other text, as it was before and is quite common I think. It helps make it stand apart from the rest of the text, otherwise you can confuse it for a regular paragraph in some cases. On various compositing index pages I noticed there is too much spacing. The solution may be to edit those pages to remove the horizontal lines, they seem to be the only index pages using them like this. | Old | New | |-|-| | ![compositing_old.png](/attachments/24a81abe-550e-4de5-95d1-8685768c4e9f) | ![compositing_new.png](/attachments/c87a62cf-c241-40ec-9a91-57c408c2490d) |

compositing_new.png

149 KiB

compositing_old.png

136 KiB

👍 1

Brecht Van Lommel approved these changes 2024-03-18 01:25:59 +01:00

Dismissed

Brecht Van Lommel left a comment

No need for me to review this further I think, my comments are not blocking.

Campbell Barton approved these changes 2024-03-18 02:38:17 +01:00

Brecht Van Lommel approved these changes 2024-03-19 11:45:04 +01:00

Francesco Siddi commented

2024-03-20 02:32:12 +01:00

On a side note, I have kept the google analytics but I have noticed some Blender sites have been using https://analytics.blender.org is that service still in testing?

Perhaps @fsiddi can answer this question. I can switch the manual to use that service if desired.

Please remove Google Analytics, it's been replaced with a self-hosted Plausible instance. Use this code instead:

<script defer data-domain="docs.blender.org" src="https://analytics.blender.org/js/script.js"></script>

> On a side note, I have kept the google analytics but I have noticed some Blender sites have been using https://analytics.blender.org is that service still in testing? > > Perhaps @fsiddi can answer this question. I can switch the manual to use that service if desired. Please remove Google Analytics, it's been replaced with a self-hosted Plausible instance. Use this code instead: ``` <script defer data-domain="docs.blender.org" src="https://analytics.blender.org/js/script.js"></script> ```

Aaron Carlisle changed target branch from main to blender-v4.1-release

2024-03-20 21:23:29 +01:00

Aaron Carlisle force-pushed furo-theme from 5b789ef42b to c42be80e8d

2024-03-20 21:28:48 +01:00

Compare

Aaron Carlisle merged commit c2ad66965b into blender-v4.1-release

2024-03-20 21:38:49 +01:00

Aaron Carlisle deleted branch furo-theme

2024-03-20 21:38:50 +01:00

Aaron Carlisle referenced this issue from a commit

2024-03-20 21:39:56 +01:00

Switch the manual theme to Furo

Aaron Carlisle referenced this issue from a commit

2024-03-20 21:42:09 +01:00

Switch the manual theme to Furo

Sign in to join this conversation.

No reviewers

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Switch the manual theme to Furo #104735