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 added 1 commit 2024-03-15 03:02:06 +01:00

289888567a Switch the manual theme to Furo

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

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.

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 added 5 commits 2024-03-17 18:16:13 +01:00

6997b2e1cd Remove jquery extension

4df0a6b1ce Let the theme choose the 'pygments_style'

f59be11211 Cleanup: Remove css fixes from old theme

7fe71b41ad Cleanup: better organize theme css overrides

- Place "fixes" near top of file
- Place our custom stuff near the bottom

efc7daa711 FIgures: Improve captions

- Make text use the secondary font color
- Decrease whitespace above caption
- Increase whitespace below caption

Aaron Carlisle added 3 commits 2024-03-17 19:07:57 +01:00

35210cf7fb Force admonition to span the full width if close to a figure

48ed10ed53 Improve contrast of reference admonitions

824848f2cb Adjust kbd styles to our liking

- Style the parent kbd element and not the individual children

Aaron Carlisle added 1 commit 2024-03-17 19:32:05 +01:00

2a77021048 Adjust heading font size to our liking

Aaron Carlisle added 3 commits 2024-03-17 19:57:28 +01:00

29d9b7cfb6 Style menuselection the same as kbd

23394ee2cd Dont decrease font size of kbd and menuselection

68f29cdbaa Small tweaks to kbd and menuselection

Aaron Carlisle added 1 commit 2024-03-17 20:45:20 +01:00

3370cce7c3 Tweaks to kbd, menu selection

- Vertical-align baseline
- Keep styling in definition terms

Aaron Carlisle added 2 commits 2024-03-17 21:06:24 +01:00

37e20b6c8f Directly edit when using the pencil icon

6877c8fbff Fix: Building without furo

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_old.png

136 KiB

compositing_new.png

149 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

Aaron Carlisle added 1 commit 2024-03-18 04:22:22 +01:00

4e304eb04c Merge branch 'main' into furo-theme

Aaron Carlisle added 6 commits 2024-03-19 02:03:55 +01:00

4d5e000a02 Fix Field Lists with short terms

0d7ceed49e Improve HR and toctrees

3d229e365e Make text smaller for captions

44e12e0689 Merge branch 'main' into furo-theme

a7584ae2f4 Use Blender Blue as the brand color

9271b23fff Adjust external links dynamically

Aaron Carlisle added 2 commits 2024-03-19 02:16:29 +01:00

5b87c1d7cd Add rubrics to heading customizations

b12c73b48a Add animation to sidebar arrow

Aaron Carlisle added 2 commits 2024-03-19 02:51:19 +01:00

19541bff0f Small fixes to toc trees

e6d6d36436 Increase the font sizes of various text

Aaron Carlisle added 2 commits 2024-03-19 03:19:19 +01:00

0e72c136cb Version Switch: Fixes for dark mode

d0c22787f7 Hide contribute links when printing to PDF

Aaron Carlisle added 1 commit 2024-03-19 05:09:53 +01:00

d822e28f09 Cleanup: Remove unused CSS

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 added 2 commits 2024-03-20 03:46:54 +01:00

524c957931 Cleanup: Whitespace

5b789ef42b Remove google analytics

Blendify 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