DOC: Documentation should be available for different versions

[Kai-Striega]

Issue with current documentation:

The current documentation shows only for version 1.0

Idea or request for content:

The documentation should show for "dev" and any released versions. This way users can access the documentation for their version.

Take a look at https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html

[AbhiRKeesara]

Hi @InessaPawson

I'd like to work on this as part of the NumFOCUS Sustaining Open Source Series program.

I've explored the repo and see that versioned docs already exist on gh-pages:

• /version/0.1.0/
• /version/0.2.0/
• /version/1.1.0/
• /dev/

What's missing is the version switcher UI to let users navigate between them.

Proposed plan:

1. Add version switcher to conf.py

   • Configure html_theme_options["switcher"] (pydata-sphinx-theme already supports this)
   • Add "version-switcher" to the navbar

2. Create switcher.json

   • Add entries for dev + all deployed versions (0.1.0, 0.2.0, 1.1.0)
   • Host at a stable URL (e.g., /dev/_static/switcher.json so all versions reference the same file)

3. Automate switcher.json updates

   • Modify publish_docs_to_pages.yml to auto-update switcher.json when new versions are deployed
   • This ensures new releases automatically appear in the dropdown

Note: I noticed v1.0.0 has a tag but no docs deployed. I'll skip it in this PR to keep scope focused. Happy to backfill in a follow-up PR if needed.

Question: Any preference on where switcher.json should live?

Happy to start on a PR!

[Letme]

Model it the same as official numpy documentation. That way it is familiar to maintain between both repos.

[AbhiRKeesara]

@Letme Thanks for the guidance! I'll model it after numpy's setup:

• versions.json at the doc root (/_static/versions.json)
• Same html_theme_options structure with navbar_end and switcher config
• Include show_version_warning_banner option

I'll study numpy's doc/source/conf.py and match the pattern. Will share a PR once ready!

[mattip]

The numpy-financial documentation lives on the gh-pages branch, unlike the numpy documentation that lives in a separate repo.

One more thing: the homepage should redirect to latest/index.html, rather than show the content it does today

[AbhiRKeesara]

@Letme and @mattip - Thanks for your guidance. The PR #153 adds a version switcher modeled after NumPy's docs pattern, and includes the redirect to /latest/ you suggested. The redirect and latest symlink will take effect on the first release tag push after the PR is merged.