menubar of website does not work on mobile

[jasmainak]

Title says it all ... the menubar of the hnn-core documentation used to work on mobile in the past but it's not clickable anymore. I tried using safari on iphone 13

[asoplata]

Maybe related, the "version switch" dropdown does not work on the current version, in that it doesn't display the older versions. However, in older versions like https://jonescompneurolab.github.io/hnn-core/v0.3/ , the dropdown does work, and you can get to the current (default page) stable version. You just can't get back from it.

[jasmainak]

maybe you can use git bisect to figure out which commit broke it?

[asoplata]

I will note that the issue with the menubar is not limited to just mobile, but affects desktop versions of the website as well. We need to fix this before I can start revamping the code website. I've tried digging, but I honestly don't understand what is the fundamental cause of the issue. However, I think there's a chance that whatever fixes the version menubar dropdown issue will also fix #941.

• Context: the actual problem
  • The problem may be that @ntolley (NT) did build and push the docs, but did NOT push an actual v0.4 github tag, or update __init__.py 's version (instead of 0.4rc0). Additionally, when the v0.4 docs were added and set as the new stable, the "development" version should have been incremented to 0.5, both in doc/conf.py and __init__.py. It's possible (I'm not convinced) that this is causing the problem.
    • It's difficult (maybe impossible) to determine if this is the issue without explicitly making said tag, or making changes to the gh-pages branch
    • I don't know if this would actually fix the dropdown issue. Part of what I don't understand is that the existing links in the dropdown SHOULD point to existing gh-pages subdirs.
    • One possibility is there were issues with the build environment that was used to create the docs: one small piece of evidence for this is that for the stable docs, mpi4py wasn't actually installed: https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/howto/plot_simulate_mpi_backend.html#sphx-glr-auto-examples-howto-plot-simulate-mpi-backend-py .

1. Option 1: We un-do NT's v0.4 documentation push, and pretend they never happened.
   • This requires undoing this commit and maybe some others: d89d0f9
     1. The current "stable" is replaced with v0.3 (which it arguably should be)
     2. branch "maint/0.4" is deleted (since v0.4 is in development, NOT maintenance)
     3. the folder "v0.4" in branch "gh-pages" is deleted
   • The current version would stay like it is, v0.4rc4 or whatever. However, the documentation for it would only be live on the "development" branch of the website. If the dropdown works for the v0.3 and stable versions of the website, but not development, then that implies the issue is not due to improper versioning.
   • This may not fix the dropdown issue and other issues like the search. However, it may, since the default website would revert to the v0.3 version, which does appear to work.
   • This would redefine the "stable" verrsion of the website: it would NOT reflect the old version of 0.4 that NT pushed, but instead show v0.3. However, when we finish our v0.4 changes, those should work correctly then since it would be a complete release (including with git tags, etc.).
   • To be clear, since we never had an "official" v0.4 release, this is more correct, since we are still arguably in the 0.4 development cycle.
   • Due to the complexity of the doc build system, this is probably our best option to do now, and we can switch to a fundamentally different system later.
   • This is equivalent to letting Austin tinker with the gh-pages branch.
2. Option 2: (I really don't like this) We "artificially" increment the version for the sake of the documentation.
   • We would still have to re-build the v0.4 documentation based on the current master and overwrite NT's prior v0.4 doc pushes.
   • Note that our "current" version would then be updated to be v0.5dev or something similar
   • We would NOT have to publish this as an actual version on Pypi.
   • I think this is less likely to solve the issue.

[jasmainak]

@asoplata It's very detailed but too much text to quickly glance and give accurate feedback :) Let me ask:

• are you able to build a version of the doc locally on the master / main branch that works?
• If yes, perhaps the simplest solution is to overwrite the respective folders in the docs website

Also happy to meet on an ad hoc basis (say, once a month or once in 15 days) if you need help with these kind of issues. I am sure I can help you debug. Regular weekly meetings are harder ...

[asoplata]

No. All new local builds of the docs I have tried also have the same issue, where the version dropdown no longer works.

However, I have good news, I may have found the issue: it may be with sphinx-bootstrap-theme itself actually: https://github.com/ryan-roemer/sphinx-bootstrap-theme . Specifically, dropdowns similar to our Page navbar entry and version list no longer appear to be working for the theme as a whole: ryan-roemer/sphinx-bootstrap-theme#227 . The first example here https://sphinx-themes.org/sample-sites/sphinx-bootstrap-theme/ illustrates the same problem. The repo hasn't had a release in about 3 years, and appears abandoned.

Fortunately, I believe we will be able to re-enable version switching if we, like MNE, switch to the actively-updated Pydata Sphinx theme (very limited example: https://github.com/mne-tools/mne-python/pull/10605/files ). This also has the nice quality of allowing us to define all our versions in a JSON file (see https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/version-dropdown.html ) rather than as raw html that is added via templating.

[jasmainak]

I suspected as much! Thanks for digging it up. If the repo is not maintained, we should certainly switch to another theme. +1 for doing that. What steps do we need to take for making that switch?