docs: consider switching to sphinx-book-theme

[ltalirz]

As shown by @chrisjsewell , the sphinx-book-theme offers a couple of nices features, including:

• suggesting edits
• opening issue for the page one is looking at
• downloading a page as PDF

I'm interested particularly in lowering the barrier for users to give feedback on the documentation - part of it is perhaps just textual: we currently have an "edit this page" button but I think "suggest edit" is actually what we want people to see. Having a way to open an issue on a particular documentation page also seems like a very good idea.

I just discussed with @chrisjsewell and he suggested to wait a few weeks until there is a stable release.

It should mainly just be replacing pydata-sphinx-theme with sphinx-book-theme

[chrisjsewell]

Yep FYI: sphinx-book-theme literally inherits from pydata-sphinx-theme, so it should be too difficult to change over in a test branch see what the docs look like. We've got a few imminent improvements in the pipeline, which is why I suggested to wait just a little bit

[chrisjsewell]

Note, sphinx-book-theme is just about there now with the improvements I mentioned (by moi as one of its maintainers): https://sphinx-book-theme.readthedocs.io/en/latest/ (e.g. expandable sections in the left ToC), and as mentioned in #5006, @mbercx has already taken the plunge to use it in https://aiida-tutorials.readthedocs.io/en/tutorial-2021-intro/ 😄

[mbercx]

@mbercx has already taken the plunge to use it in https://aiida-tutorials.readthedocs.io/en/tutorial-2021-intro/ 😄

And a deep dive it was 😅

[ltalirz]

@chrisjsewell Is there any reason to wait more for this or is this switch up for grabs?

[chrisjsewell]

No go for it, all the options are here: https://sphinx-book-theme.readthedocs.io/en/latest/customize/index.html#theme-options

and also switch sphinx-panels to sphinx-design: https://sphinx-design.readthedocs.io/en/sbt-theme/get_started.html#migrating-from-sphinx-panels

[ltalirz]

@chrisjsewell will take care of this once sphinx-book-theme has further consolidated, see https://github.com/aiidateam/aiida-core/pull/5368