Fix version switcher on readthedocs

[agriyakhetarpal]

Description

This updates the version switcher styling on readthedocs and configures a .json file for the version switcher dropdown

Fixes #2766

Type of change

Please add a line in the relevant section of CHANGELOG.md to document the change (include PR #) - note reverse order of PR #s. If necessary, also add to the list of breaking changes.

• New feature (non-breaking change which adds functionality)
• Optimization (back-end change that speeds up the code)
• Bug fix (non-breaking change which fixes an issue)

Key checklist:

• No style issues: $ pre-commit run (see CONTRIBUTING.md for how to set this up to run automatically when committing locally, in just two lines of code)
• All tests pass: $ python run-tests.py --all
• The documentation builds: $ python run-tests.py --doctest

You can run unit and doctests together at once, using $ python run-tests.py --quick.

Further checks:

• Code is commented, particularly in hard-to-understand areas
• Tests added that prove fix is effective or that feature works

[agriyakhetarpal]

The reason why all the versions are being shown in green is because json_url is not configured in html_theme_options yet, I shall do that in this PR

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (ac0acd6) 99.68% compared to head (b0e4c04) 99.68%.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #2769   +/-   ##
========================================
  Coverage    99.68%   99.68%           
========================================
  Files          272      272           
  Lines        19007    19007           
========================================
  Hits         18948    18948           
  Misses          59       59           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[agriyakhetarpal]

@tinosulzer the readthedocs build is passing but I can not test how it would look like (if it will show versions with the correct colour scheme when hosted) – I added the version switcher dropdown to the header like you requested but it is currently not including past versions on my local build and shows up blank:

Though this configuration matches that of the numpy docs, which is why I suspect it should work as intended.

Also, the new file docs/_static/versions.json will have to be updated with the latest version on the creation of each release. Right now there's the option "check_switcher": True in html_theme_options but that can only test whether versions.json can be found/read, and not if the file includes the latest version. Happy to write some sort of check or a warning for this if needed in the existing workflows if you could guide me with it

[valentinsulzer]

To keep the version up to date, add the appropriate code to https://github.com/pybamm-team/PyBaMM/blob/develop/scripts/update_version.py. This file gets run automatically at the end of every month to update the version in the various places it needs to be updated.

Also, make sure your changes don't kill the existing day/night switch and social links

[agriyakhetarpal]

I added the code to update the json and tested it, though it messes up the formatting after doing so. Should still be readable

Also, make sure your changes don't kill the existing day/night switch and social links

I am assuming that shouldn't happen because the code for them was already commented out, and also because the links do not show up on building the docs locally, but do so when hosted on readthedocs

[valentinsulzer]

You can see the built docs here, it's missing the links https://pybamm--2769.org.readthedocs.build/en/2769/
I think when "navbar_end" is not specified it defaults to the day/night and link checker, which is why they were removed by you adding a "navbar_end" without them included

[agriyakhetarpal]

That makes more sense, I updated it to include the links and the day/night button. Also TIL one can see the docs built from a PR this way

[agriyakhetarpal]

I was able to show the versions in the dropdown locally (the colours appear in the readthedocs build). This should be ready to merge now

This was done by adding the .json file at a static URL (tried it with a link to the raw file in this PR) – I was not able to get it to work with a local file:/// URL despite multiple tries (according to the second point in the docs), but remote URLs do work. So I put a link to https://pybamm.readthedocs.io/en/latest/_static/versions.json as the first point suggests; this link currently returns a 404 (fails Lychee as well), but that would be fixed after this PR gets merged and versions.json gets added to the codebase.

[valentinsulzer]

Looks good, thanks!