search

aiidateam / aiida-core

The official repository for the AiiDA code
https://aiida-core.readthedocs.io
Other
431 stars 187 forks source link

docs: consider switching to sphinx-book-theme #4441

Open ltalirz opened 3 years ago

ltalirz commented 3 years ago

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

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 image 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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

@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 commented 2 years ago

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

chrisjsewell commented 2 years ago

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 commented 2 years ago

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