DOC: Documentation should be available for different versions #78

Activity

1. Kai-Striega

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   on Nov 19, 2023
2. Kai-Striega

   added this to the 2.0 milestone on Nov 19, 2023
3. InessaPawson

   added this to NF Sustaining Open Source Series 2026on Sep 15, 2026
4. github-project-automation

   moved this to Open in NF Sustaining Open Source Series 2026on Sep 15, 2026
5. InessaPawson

   added

   sustain-2026

   on Sep 15, 2026
6. AbhiRKeesara commented on Sep 17, 2026

   

   AbhiRKeesara

   on Sep 17, 2026

   Contributor

   More actions

   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!
7. Letme commented on Sep 17, 2026

   

   Letme

   on Sep 17, 2026

   More actions

   Model it the same as official numpy documentation. That way it is familiar to maintain between both repos.
8. AbhiRKeesara commented on Sep 17, 2026

   

   AbhiRKeesara

   on Sep 17, 2026

   Contributor

   More actions

   @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!
9. mattip commented on Sep 17, 2026

   

   mattip

   on Sep 17, 2026

   Last edited by mattip

   Member

   More actions

   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
10. AbhiRKeesara

    added a commit that references this issue on Sep 17, 2026

    DOC: Add version switcher to documentation

    ...

    This issue will close once commit 83d329f is merged into the 'main' branch.

    83d329f
11. github-project-automation

    moved this from Open to In Progress in NF Sustaining Open Source Series 2026on Sep 17, 2026
12. AbhiRKeesara commented on Sep 17, 2026

    

    AbhiRKeesara

    on Sep 17, 2026

    Last edited by AbhiRKeesara

    Contributor

    More actions

    @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.
13. AbhiRKeesara

    added 2 commits that reference this issue on Sep 17, 2026

    DOC: Add version switcher to documentation

    ...

    This issue will close once commit 1073f61 is merged into the 'main' branch.

    1073f61

    DOC: Add version switcher to documentation

    ...

    This issue will close once commit 2b7ac96 is merged into the 'main' branch.

    2b7ac96
14. mattip

    closed this as completedin #153on Oct 18, 2026
15. github-project-automation

    moved this from In Progress to Complete in NF Sustaining Open Source Series 2026on Oct 18, 2026
16. AbhiRKeesara commented on Oct 18, 2026

    

    AbhiRKeesara

    on Oct 18, 2026

    Contributor

    More actions

    Hi @mattip, thanks for reviewing and merging the changes. While clicking through the live docs, I noticed two things.

    The switcher shows up on the dev docs (https://numpy.org/numpy-financial/dev/), but not on the stable docs, since latest still points to the 1.1.0 build from before this change (something I should have flagged in the PR description). As https://numpy.org/numpy-financial/latest/index.html is the page most users land on, it would be great for it to show the switcher. If you'd like it sooner than the next release, I'm happy to open a PR against gh-pages that rebuilds the 1.1.0 docs with the switcher.

    Also, the 0.1.0 and 0.2.0 docs use the older layout without a switcher, so once you go there from the dropdown, the only way back is the browser's back button. That seems fine to me for old versions, but wanted to flag it.

    Dev docs (switcher in the navbar):

    

    Stable docs via latest (no switcher):

    

    0.2.0 docs (older layout, no switcher):