-
Notifications
You must be signed in to change notification settings - Fork 1.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Tweak website structure #12572
base: main
Are you sure you want to change the base?
Tweak website structure #12572
Conversation
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 |
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/).
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
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.
👎🏻 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.
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.
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?
Re-write the "last updated" JS snippet to use vanilla JS instead of JQuery.
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? |
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. |
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)?
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
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.
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. |
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. |
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. |
I just realized we already have something similar here: https://mne.tools/dev/install/index.html Maybe this could serve as a starting point? |
Here's my suggestion for a new navigation structure (main navbar items):
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. |
For the landing page, I'm +1 to remove the sidebar if: (1) the topbar is restructured. Some items from the Proposal for the top bar:
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. For the landing page tiles, +1 to modify them as you want. 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 ;) |
Thanks @mscheltienne!
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) |
To be tested, but it might fit, most names are short and we got rid of the long |
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). |
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. |
As initially discussed in #12558, this PR aims to tweak the structure and content of our website. Here are my suggestions:
Rendered website with all current changes:
https://output.circle-artifacts.com/output/job/957a9bd1-8b34-4717-b10d-606dc54cbec3/artifacts/0/html/index.html