Choose a theme for the documentation

Organisation
1

It seems that soon readthedocs will remove the default theme: Doctools without configuration file (conf.py / mkdocs.yml) are deprecated — Read the Docs Blog and Missing sphinx_rtd_theme · Issue #10626 · readthedocs/readthedocs.org · GitHub

So we will have to pick a theme. Of course we can keep the sphinx_rtd_theme but I guess this gives us the opportunity to choose maybe a better them for us.
I think we should limit our choice to https://sphinx-themes.org/ as they are supposed to be maintained.

Here is my shortlist:

We need to have a theme that is responsive, that render well python code and that render well the directives we use like menuitem, guilabel, warning, note etc. It is also good if we can make it looks like our website.

I will post a poll in few days after having collected thoughts or suggestions.

2

I like the Book Theme.

3

So it become clearer that rtd is going to remove its default theme: Build: do not set `sphinx_rtd_theme` theme automatically by humitos · Pull Request #10638 · readthedocs/readthedocs.org · GitHub

So I guess we could just define a theme for the latest version and we will have older versions rebuild with the default sphinx theme (instead of sphinx_rtd_theme). This will avoid to modify all packages of every supported series.

4

Here is the poll:

Theme for the documentation
  • Readthedocs
  • Material
  • Awsome
  • Book
0 voters
5

Currently the Awesome Sample | Awesome theme seems broken.

6

You can see it in action on https://sphinxawesome.xyz/

7

For the record, Book and Read the Docs themes have a lower score than the Awesome on Page Speed:

I think it is an important criteria to take into account.

8

You’re comparing performance using different servers, are you sure Awesome is much better when served by the same hardware/datacenter/etc?

9

Accessibility is also an import measure. And looking at the performance, it is about the difference between 1.8 and 2.4 seconds. With high traffic websites that can be an issue, but for documentation I don’t think so.

10

I updated the Page speed link to use the same working sphinx themes server.

11

But you also have to use the most recent version of the theme. I now see a big difference between
Book Sample — Book (link from @udono) and Book Sample — Book (link for pagespeed). I have no idea which is the most recent one.

12

Here is Use Sphinx book theme for documentation (!768) · Merge requests · Tryton / Tryton · GitLab

13

I think that this module title is very illegible:
imagen

14

It will be good to have fast review because for now any new documentation build use the generic default theme (which is not optimal).

15

That’s not the right theme. It’s the default Alabaster theme which is the default theme since version 1.3 of sphinx (quoted from their github page).

1 Like
16

With the theme now active, I found that the main-content doesn’t keep the whole width but the minimum. This is not looking great. Changing the flex-grow from 0 to 1 of the .bd-main class will fix this. No idea if this can be added as custom css.

17

You can make a change proposal to the theme provider.