Tweak website structure

[cbrnr]

As initially discussed in #12558, this PR aims to tweak the structure and content of our website. Here are my suggestions:

1. Remove sidebar from main page, and move the sidebar items to the main menu (navbar). This is already implemented here.
2. The sidebar is useful on many subpages, such as the API, but there are some pages where it is empty and therefore should be removed, e.g. Cite and Contribute. Any hints on how to selectively remove the sidebar welcome!
3. I would also like to remove the "Section Navigation" heading of the sidebar. Any ideas?
4. Move the Contributors gallery to a separate page, since it really clutters our landing page. I suggest to move them to Development.
5. The Funders could also be moved to a separate page, and maybe only current funders could be shown on the main page.
6. The six feature boxes should be simplified. One issue is that they don't respect the "minimal motion" browser setting. Another issue is that when hovering over a box, no text/description is shown. I suggest to completely remove all motion effects on hover.
7. The version menu is still broken, according to @drammock this is probably due to a missing jQuery. How would I be able to fix it?
8. I think we should move all versions < 1.0 to the archive. This was discussed in #11885, and the suggestion was to keep the last 2 years in the menu. This would be 1.0.0 now.

Rendered website with all current changes:

https://output.circle-artifacts.com/output/job/957a9bd1-8b34-4717-b10d-606dc54cbec3/artifacts/0/html/index.html

[hoechenberger]

The six feature boxes should be simplified. One issue is that they don't respect the "minimal motion" browser setting. Another issue is that when hovering over a box, no text/description is shown. I suggest to completely remove all motion effects on hover.

I imagine we keep the images and text but arrange the tiles / cards such that the text and images are always visible; on hover, the entire tile outline could receive a border

[hoechenberger]

I imagine we keep the images and text but arrange the tiles / cards such that the text and images are always visible; on hover, the entire tile outline could receive a border

Maybe a bit like on the Spyder website, even though I would prefer a permanently visible border around the cards that would show a hover effect:

https://www.spyder-ide.org

[drammock]

1. Remove sidebar from main page

I'm -0.5 on this (open to changing my mind if the right alternatives are found). I for one really have always appreciated having a single click to get to the tutorials page and the contrib guide, and if I imagine a new-to-MNE user coming to our website seeing a prominent link called "tutorials" seems good, rather than having to first click "documentation" (would they know to start there? maybe they don't know what "API" means and start there instead, and get overwhelmed?). Second point is that sometimes it's even useful to have the dev version string (with hash incorporated) visible.

That latter point would be moot if we could get the dev version string to display in the version switcher (instead of the current "dev") --- I think scipy's dev docs do this so we could look there for inspiration; or we could print it small in the footer. But the former point is harder for me to think of a workaround for... maybe if we completely nix the neuroscience-specific gallery tiles and replace them with something more like what NumPy has? (https://numpy.org/doc/stable/).

2. The sidebar is useful on many subpages, such as the API, but there are some pages where it is empty

Which sidebar are we talking about here, the left or the right one? On the dev docs, the cite page and the contributor guide neither one is empty. Your links go to the PR build; I suspect something about this PR caused them to be empty errantly.

That said: if you want to remove the left sidebar from a single page:

   html_sidebars = {
     "pagename": [],
     "other_page_name": []
   }

if you want to remove the right sidebar from a single page: https://pydata-sphinx-theme.readthedocs.io/en/stable/examples/in-page-toc.html#turn-off-the-right-sidebar-for-a-single-page

3. I would also like to remove the "Section Navigation" heading of the sidebar. Any ideas?

IIRC that isn't configurable? There was some discussion about it on the theme's repo in the last 6-12 months maybe... but I think that was about making it translatable not configurable. I suggest searching the theme repo issues though, in case my memory is wrong.

4. Move the Contributors gallery to a separate page

👎🏻 again it would be helpful if you would link to past discussions of these issues. There has been a lot of discussion about how to give credit more equitably (mostly in #11605) but also in dev meetings. #11819 was a small step toward addressing that; moving them off the homepage is a step backwards in my mind. If you're concerned about screen real estate, we can adjust the size of the avatars (cf. #11819 (comment)) but AFAIC it doesn't really matter how much space they take up because they're the last item on the page.

5. The Funders could also be moved to a separate page, and maybe only current funders could be shown on the main page.

I don't feel super strongly about this one, but I do disagree, because (1) as mentioned above I don't see the problem with the homepage being long when it's mostly avatars and logos, and (2) keeping only the "active" funders on the homepage is more work because someone needs to keep track of which grants are active, then make extra PRs to move/remove inactive funder logos later.

6. The six feature boxes should be simplified. One issue is that they don't respect the "minimal motion" browser setting. Another issue is that when hovering over a box, no text/description is shown. I suggest to completely remove all motion effects on hover.

Definitely 👍🏻 to respect minimal motion settings. I'm also not married to the zoom/alpha effects even for browsers with "maximal motion" set. One idea mentioned above was to emulate NumPy's docs homepage (tiles with icons linking to important/popular destinations); another idea is to emulate the "case studies" tiles on NumPy's global landing page. WDYT?

7. The version menu is still broken, according to @drammock this is probably due to a missing jQuery. How would I be able to fix it?

Re-write the "last updated" JS snippet to use vanilla JS instead of JQuery. git grep -i "last.updated"

8. I think we should move all versions < 1.0 to the archive.

Where is "the archive" exactly? Does the menu include a link to that "archive"? Can you link to the prior discussion of this, where IIRC some concrete ideas where proposed?

[cbrnr]

Re 1, neither NumPy nor SciPy have a sidebar on their homepages. If you want Tutorials to be directly visible, let's restructure the menu items then! For example, why do we have "Documentation"? Isn't the entire website documentation? "Help" is similarly questionable, and "Development" is very similar to "Contribute".

So I think we should come up with a new organization of our main navbar entries.

Re 2, I was talking about the left sidebar. And you're right, I've messed it up a bit in this PR, because I moved the sidebar entries to the main navbar. Any suggestion on how to do this properly?

Re 3, yeah, I couldn't find anything, it would have been nice to be able to remove it, but not super important.

Re 4, since we're always trying to find good examples in how other projects handle things, neither SciPy nor NumPy nor Scikit-Learn nor Pandas show their contributors on their homepages. I'm not against having that gallery, just move it somewhere else.

Re 5, if we move the contributors gallery, I'm OK with keeping funders and logos.

Re 6, yeah, something simple like that 👍!

Re 7, OK!

Re 8, it's in the version menu, last entry at the bottom. The discussion is in the link a provided.

[drammock]

Re 1, neither NumPy nor SciPy have a sidebar on their homepages.

Not exactly true. Both NumPy and SciPy have a separate global homepage that isn't built by Sphinx (it's built with Hugo in a theme meant to roughly match the Pydata Sphinx Theme). The NumPy docs homepage (the root page of their sphinx build) does have a sidebar (containing only a search field): https://numpy.org/doc/stable/ Same is true of SciPy: https://docs.scipy.org/doc/scipy/

We don't have this separation of main site vs docs site. That doesn't mean the comparison of "our Sphinx homepage vs their Hugo homepage" is invalid though! It's possible to not have a sidebar on our (Sphinx-built) homepage --- but for me, willingness to part with the quick links box requires a concrete proposal of what the new site structure will be (as you say). So in your view, what should be the top-level headings be and what secondary headings are below them (and in what order)?

Re 2, I was talking about the left sidebar. And you're right, I've messed it up a bit in this PR, because I moved the sidebar entries to the main navbar. Any suggestion on how to do this properly?

You've put "Cite" in the top-level TOC, and the "Cite" page doesn't declare a (hidden) TOC of pages that should be "under" it. So in a case like that where a top-level page has no children, the right approach is probably to remove the sidebar using conf.py (html_sidebars = { "documentation/cite": [] } or so). That said: the folder structure of our docs mirrors the site organization which means that moving "Cite" to the top level should also involve changing its place in the folder heirarchy (so cite.rst moves up one folder level, and the above snippet becomes html_sidebars = { "cite": [] }). This also changes the URL, so typically when we do that we also create redirects (to minimize the pain for folks who had pages bookmarked).

Re 4, since we're always trying to find good examples in how other projects handle things, neither SciPy nor NumPy nor Scikit-Learn nor Pandas show their contributors on their homepages.

Fair enough, though pandas has ~3000 contributors, we have more like 300, so it's a slightly different decision for them than for us. It's always a judgment call whether what other projects are doing is better or worse than what we're doing. Personally I think prominently featuring our contributors is better than not doing so, but we're free to disagree about that.

Re 8, it's in the version menu, last entry at the bottom. The discussion is in the link a provided.

Sorry, I missed the link the first time through (and forgot that we already implemented the cutoff, and you're just suggesting here to update which version the cutoff starts at). FWIW in #11885 (comment) I suggested 3 years rather than 2 as the cutoff, and I still agree with the reasoning behind that (in fact, I just last week revived an old stalled project, and its env is running MNE 0.24, so I personally would benefit from having a longer cutoff window / not having 0.24 accessible only as a ZIP).

It would also be nice if we could find a way to automate moving the cutoff / not have to manually change it every year, or at least make it part of the release process so that it happens regularly without someone needing to remember.

[cbrnr]

Re changing/removing the side bar heading (currently "Site Navigation"), I only found this PR (with related discussion in the linked issue(s)), but I honestly have no idea what was changed and how to use it. I assume it is now possible to hide the "Site Navigation" heading (and not the entire sidebar)?

I'll reply to the other points soon, including a suggestion for a navbar structure.

[drammock]

Re changing/removing the side bar heading (currently "Site Navigation"), I only found this PR

Ah yes. That won't help you I'm afraid. It suppresses the heading text when the site is in narrow-screen layout. It doesn't allow to customize or remove it entirely.

[hoechenberger]

I imagine we keep the images and text but arrange the tiles / cards such that the text and images are always visible; on hover, the entire tile outline could receive a border

Maybe a bit like on the Spyder website, even though I would prefer a permanently visible border around the cards that would show a hover effect:

https://www.spyder-ide.org

I just realized we already have something similar here:

https://mne.tools/dev/install/index.html

Maybe this could serve as a starting point?

[cbrnr]

Here's my suggestion for a new navigation structure (main navbar items):

• Install
• Tutorials
• Examples
• Contribute
• API
• More
  • Changelog
  • Cite

Examples could be removed, because they are already available from the Tutorials page (in the left sidebar).

With this structure, I'd remove the left sidebar only from the homepage. This creates more horizontal space, which should benefit the overall look.

[mscheltienne]

For the landing page, I'm +1 to remove the sidebar if:

(1) the topbar is restructured. Some items from the Documentation left sidebar are missing from your proposal: Glossary, Implementation details, DEsign philosophy, The typical M/EEG workflow, ... alternative proposal below.
(2) the development version string including the hash appears somewhere simple to see on all dev builds. I don't believe showing this version in the drop-down menu will render correctly, but we could add it to the development only banderole This is documentation for the unstable development version of MNE-Python..

Proposal for the top bar:

• Install
• Tutorials, with 2 items in the left sidebar:
  • Tutorials
  • Examples
• TBD (I don't have name here..)
  • The typical M/EEG workflow
  • Migrating from other analysis software
  • Command-line tools
  • Design philosopy
  • Implementation details
  • Example datasets
  • Glossary
• FAQ where Getting started with python and FAQ are merged (no left bar on this one)
• API
• Cite, with 2 entries:
  • How to cite MNE-Python
  • Papers citing MNE-Python
• Development, with:
  • Contributing guide
  • Changelog
  • Roadmap
  • Project governance

The rational is to target new comers. People already familiar with MNE will know that they can run a search on the website or go to the API page to look for the function they want. But newcomers have to first land easily on a couple of very interesting pages. IMO, install, tutorials, Typical M/EEG workflow, Migrating from other softwares, FAQ are the most important ones and should not be hidden.
Next, properly citing MNE-Python and showing that it is cited and used is equally important. That's why I would prefer a dedicated entry in the new menu.

For the landing page tiles, +1 to modify them as you want. sphinx-design tiles should work nicely? That's probably what is used for the install page.

For the funding partners and contributors on the frontpage, -1 to remove them. I don't mind having the bottom of our landing page filled with logos. It's not text that people have to read, there is nothing extra-important that compels you to scroll down on the landing page, and I believe giving credit to our contributors is important. We are not pandas, numpy, scipy with thousands of contributors, IMO we need every bit of motivation to get new ones ;)

[hoechenberger]

Thanks @mscheltienne!

Proposal for the top bar:

I think these are way too many menu items, this won't fit on most screens if we also want to fit a logo, theme switcher, search button, version chooser, … in there (and in a decently large font size)

[mscheltienne]

To be tested, but it might fit, most names are short and we got rid of the long API reference and Documentation. Development can be shorten to Dev.

[cbrnr]

I'll have to think about your proposal some more, but I agree with @hoechenberger that there will probably be too many top level items. That's why I suggested to put slightly less important points into the "More" menu (e.g. I don't think we need to have a "Cite" item in the main menu).

[hoechenberger]

Development can be shorten to Dev.

I'd actually prefer if we called it Contributing or some other term that's a bit broader than "just" software development; but that's a detail

[cbrnr]

I'd actually prefer if we called it Contributing or some other term that's a bit broader than "just" software development; but that's a detail

I agree, hence my suggestion to have a "Contribute" menu item.