DOCS: Move to pydata-sphinx-theme

[chrisjsewell]

closes #4029

[chrisjsewell]

@csadorf there's a blocking issue at the moment pydata/pydata-sphinx-theme#192 😢

[jorisvandenbossche]

If you would want to use the theme before pydata/pydata-sphinx-theme#192 is properly fixed, it should be possible "relatively" easily by moving the toctrees to index.rst files in the subdirectories.

For example the toctree that is right now in source/index.rst for the installation:

.. toctree::
    :maxdepth: 1
    :caption: Installation
    :hidden:

    install/quick_installation
    install/prerequisites
    install/installation
    install/configuration
    install/updating_installation
    install/troubleshooting

could be moved to source/install/index.rst:

==========
Installation
==========

.. toctree::
    :maxdepth: 1

    quick_installation
    prerequisites
    installation
    configuration
    updating_installation
    troubleshooting

and then the main toctree in source/index.rst would become:

.. toctree::
  :hidden:

  install/index
  working_with_aiida/index
  reference/index
  ....

You already do this for some of the captions, like for reference/index

(but it is certainly good to think about if we can just support those captions in pydata/pydata-sphinx-theme#192)

[csadorf]

@csadorf there's a blocking issue at the moment pandas-dev/pydata-sphinx-theme#192 😢

That's unfortunate. How do you advise to proceed?

[chrisjsewell]

That's unfortunate. How do you advise to proceed?

I'm going to have say stick with the RTD theme for now.
Overall, I prefer the pydata theme, but its' current toctree navigation, IMO, is really a step-back from what we currently have.
So we'll keep #4029 open then I can return to it when pydata/pydata-sphinx-theme#192 is closed

[greschd]

Since I'm not actually involved in the docs revamp, I'm just looking at the new doc from time to time.. so apologies if this is either something you're planning to address or doesn't match what you're trying to do:

From my POV, it would make sense to add the "intermediate" pages as suggested by @jorisvandenbossche that show an overview of the current section (How-to, Topics, ...).

The problem I'm seeing with the current layout is that clicking on e.g. the "How to" section from the front page brings me to "How to run external codes". That's not quite what I expected, and I then need to figure out that the other "How to" guides are located in the side bar. That's not at all obvious, especially considering the sidebar can be hidden:

Note how there is no link to the other howto sub-sections visible at all.

This is less of an issue for "Installation" and "Tutorial" which have a clear starting point, but for the other four sections the chance of landing in the right page is basically 1/#sub-sections.

The new docs look fantastic overall, btw 👌.

[csadorf]

@greschd Thank you very much for the feedback! Using those "chapter landing pages" might work for How-To and Topics, but it wouldn't work for the Tutorial for example. So I can give that a shot, I'm just a bit worried that this won't work consistently.

[chrisjsewell]

but it wouldn't work for the Tutorial for example

Are we always going to have the one tutorial? Because it feels like it should just go under the getting started section if so?

[greschd]

Yeah I don't know how best to solve this in terms of toctree, but I think for the "How To" etc. the chapter landing pages are actually important regardless which style is used.

For the tutorial, "Basic tutorial" could also be at the top-level (unless there are more tutorials planned), with "how to continue" put at the same level as the other parts. But since it's a single page, I still don't know if that would work out.

[chrisjsewell]

make sense to add the "intermediate" pages

Yeh I had noted this before @greschd, but was a bit undecided on the best solution. From the point-of-view of viewing on a large screen, I do like the current layout, in terms of it being user friendly to (a) quickly understand the layout of the documentation and (b) quickly navigate to sections of the documentation (without having to click through redundant indexes). But you make a good point about implications for smaller screens.

[greschd]

I'd actually prefer the intermediate pages even on a large screen (that's how I initially tested it).

The layout of the sidebar seems perfect to me, but (disregarding how it would be implemented) ideally the top-level headers would also be clickable and lead to intermediate page.

The main point I wanted to make however is that it's slightly confusing to be brought to the "wrong" page from the front page. Even if it's technically the same number of clicks to get there, it seems like lower mental overhead to navigate "top to bottom" than "down" and then "sideways".

For the "power user" who discovered the sidebar, it probably won't matter either way 🙂

[csadorf]

The main point I wanted to make however is that it's slightly confusing to be brought to the "wrong" page from the front page. Even if it's technically the same number of clicks to get there, it seems like lower mental overhead to navigate "top to bottom" than "down" and then "sideways".

For the "power user" who discovered the sidebar, it probably won't matter either way 🙂

I think this is a very valid point though. The navigation should be as simple and obvious as possible. So we should certainly try optimize this flow.

[chrisjsewell]

See #4130 for top level indexes with RTD theme: https://137-77234579-gh.circle-artifacts.com/0/html/index.html

[chrisjsewell]

And I've just rebased this PR onto #4130: https://142-77234579-gh.circle-artifacts.com/0/html/index.html

[csadorf]

And I've just rebased this PR onto #4130: https://142-77234579-gh.circle-artifacts.com/0/html/index.html

That looks good, doesn't it?

[chrisjsewell]

That looks good, doesn't it?

I think so.

Note there's no full ToC now on the front page (which IMO would be nice), because it works a bit differently; by only showing the top-level headings for the section (on the left) and sections for the page you are in (on the right ). Click around and you'll see what I mean.
Note there is an issue open to maybe improve this for the front page: pydata/pydata-sphinx-theme#146

[csadorf]

Note there's no full ToC now on the front page [...]

I think I can live with that.

[chrisjsewell]

BTW @jorisvandenbossche in b4c4f1e I added a little CSS override for the link icon that you might want to upstream (unless it was meant to be that way), from:

to

[greschd]

I like it 👍

Absolute nit: Is it just me, or is the color-scheme a bit all over the place? For example, there are 4 blues on the front page, when counting the logo. For example the provenance graph illustrations seem to be hue-matched to the logo, do we have an "official" color palette?

[chrisjsewell]

Is it just me, or is the color-scheme a bit all over the place?

Nothing that a bit of CSS can't fix 😄 I guess the blues for the admonition boxes and buttons come from https://getbootstrap.com/docs/4.0/utilities/colors/

[chrisjsewell]

For example the provenance graph illustrations seem to be hue-matched to the logo

If you mean like https://142-77234579-gh.circle-artifacts.com/0/html/intro/tutorial.html#provenance, then they derive from

aiida-core/aiida/tools/visualization/graph.py

Line 76 in 10a5cdb

def default_node_styles(node):

[greschd]

Yeah, definitely not a high priority 😄

Exactly, those have (near as makes no difference) the same hues (only different lightness / saturation) as the logo, so I think it's on purpose. I was wondering if someone had designed a "complete" color palette.

[chrisjsewell]

I was wondering if someone had designed a "complete" color palette.

I'm pretty sure not, but happy to have a play around with it at some point, maybe not now though and when this is merged: pydata/pydata-sphinx-theme#138

[greschd]

maybe not now

Definitely, this is very low-priority. Maybe we can open an issue for that..

I can also give it a whirl if you like, but I'm not a designer by trade 😄

[chrisjsewell]

The pre-commit error is the well known "phantom error" so this is good to merge