DOC: Add version switcher to documentation

[AbhiRKeesara]

PR summary

Closes #78

What problem does this PR solve?
The documentation currently has no way for users to switch between versions. Users visiting the homepage see a static landing page rather than being directed to the latest stable docs.

Why are you interested in working on this PR?
I'm participating in the NumFOCUS Sustaining Open Source Series program and picked this issue to help improve the documentation experience.

Changes:

• Configure html_theme_options in conf.py for the version switcher (modeled after NumPy's pattern)
• Add GitHub icon link to navbar
• Update copyright year to dynamic range (2005-current) per LICENSE.txt
• Extend publish_docs_to_pages.yml workflow to:
  • Trigger on release tags (v*) in addition to main branch
  • Deploy dev docs to /dev/ and releases to /version/X.Y.Z/
  • Regenerate versions.json by scanning existing directories on gh-pages
  • Mark highest non-prerelease version as stable
  • Update latest symlink to point to newest release
  • Handle re-runs gracefully (no-op if nothing changed)
• Update RELEASE.md to reflect automated docs deployment

Simplifications per maintainer feedback:

• Generate versions.json dynamically by scanning directories instead of maintaining state
• Removed static versions.json from source (no longer needed)
• Always use absolute URL for versions.json in conf.py

Testing:

• Built docs locally with make html and verified the version switcher appears in the navbar
• Tested dropdown population using mock data
• Verified GitHub icon displays next to the version selector
• Validated workflow YAML syntax and Python heredoc syntax

Notes:

• The latest symlink and versions.json will be created on the first build after merge
• Future releases will automatically appear in the version switcher

AI Disclosure

Used AI for implementation guidance, workflow generation, code review, and drafting this description. Changes were verified locally through docs builds and manual testing.

[mattip]

Cool. Creating the index.html is a once-off, no need to do it repetitively in CI. Also creating the version json need only happen on release, not on dev builds.

[AbhiRKeesara]

@mattip - Thanks for the feedback! I'll remove the index.html creation from CI. After this PR merges, the redirect can be added once manually to gh-pages.

Regarding versions.json: the workflow currently only updates it on release builds (inside the if [ "$IS_RELEASE" = "true" ] block), not on dev builds. Am I reading your comment incorrectly, or is there something else you'd like changed there?

[mattip]

Regarding versions.json: the workflow currently only updates it on release builds

My mistake.

After this PR merges, the redirect can be added once manually to gh-pages

Why not change index.html as part of this PR?

[AbhiRKeesara]

Thanks for confirming on versions.json.

For index.html, do you mean:

1. Add a conditional check so the workflow creates it only if it doesn't exist (one-time on first release), or
2. Open a separate PR targeting gh-pages to add it directly?

[mattip]

Ahh, I see. That file only lives on gh-pages, so yes, a separate PR is needed.

[AbhiRKeesara]

@mattip Updated the workflow to remove the index.html creation. Opened a separate PR targeting gh-pages for the redirect: #154

[mattip]

LGTM now

[stefanv]

I think this PR can be simplified significantly. We can unconditionally generate the list of versions on each docs build without penalty. The docs repo, into which we're pushing, contains the list of versions already, and the latest version is stable.

I am on a phone now, but can review a bit more carefully later.

If this feels urgent, go ahead and merge then I will refactor. Otherwise polishing it up a bit will, I think, make the flow easier to follow.

[AbhiRKeesara]

@stefanv - Thanks for the feedback! No urgency on my end. Happy to wait for your detailed review and simplify based on your suggestions. The cleaner the final implementation, the better.

[AbhiRKeesara]

Hi @stefanv,

Simplified per your feedback. The workflow now regenerates versions.json by scanning dev/ and version/ directories on gh-pages on every build, so there's no static file to maintain and no state to get out of sync.

Also added safety checks for re-runs and unexpected triggers.

Happy to simplify further if you see opportunities.