feat: Implement dynamic version dropdown and static language switcher

[AR21SM]

Detailed Description:

Overview

This PR introduces a comprehensive multi-version and multi-language infrastructure for the DISCOVER Cookbook, enabling users to seamlessly navigate between different documentation versions and language translations through intuitive UI components.

Key Features Implemented

Dynamic Version Switcher

• JSON-based Configuration: Added versions.json defining available versions with URL mapping and preferred version marking:

[
    {
        "version": "2.0",
        "url": "https://discover-cookbook.numfocus.org/2.0/",
        "preferred": true
    }
]

• Sphinx Integration: Configured sphinx-book-theme switcher functionality with dynamic JSON URL loading:

html_theme_options = {
    "article_header_start": ["toggle-primary-sidebar","version-switcher","language-switcher"],
    "switcher": {
        "json_url": "https://discover-cookbook.numfocus.org/versions.json", 
        "version_match": version,
    },
}

• Version Management: Automatic version detection and display in header navigation

Multi-Language Support Infrastructure

• Language Configuration: Created languages.json supporting multiple languages with locale names, text direction, and visibility control:

[
    {
        "code": "es",
        "name_local": "Español",
        "direction": "ltr",
        "hidden": true
    }
]

• Template System: Implemented language-switcher.html template with Bootstrap dropdown functionality

• Context Variables: Added comprehensive HTML context variables for language data, current language detection, and URL generation:

# Load language data from languages.json
language_json_path = os.path.join(os.path.dirname(__file__), '_static', 'languages.json')
language_data = []
current_language_name = None
if os.path.exists(language_json_path):
    with open(language_json_path, 'r', encoding='utf-8') as f:
        all_languages = json.load(f)

# Get the current language name 
current_language_name = next((lang['name_local'] for lang in all_languages if lang['code'] == language), language)

# Filter out hidden languages for the dropdown
language_data = [lang for lang in all_languages if not lang.get('hidden', False)]

html_context = {
    "languages": language_data,
    "current_language_name": current_language_name,
    "current_language": language,
    "current_version": version,
    "baseurl": baseurl
}

• Hidden Language Support: Built-in capability to hide specific languages from public interface while maintaining backend support

Build System Enhancements

• Build Script: Created ci/build_website.sh for streamlined build process.

• Added destination_dir: dev/ for development version deployment:

- name: Push book HTML to gh-pages
  uses: peaceiris/[email protected]
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./DISCOVER/_build/html
    destination_dir: dev/
    keep_files: true

This implementation establishes a robust foundation for the DISCOVER Cookbook's evolution into a multi-version, multi-language documentation platform while maintaining seamless user experience.

[AR21SM]

Hi @OriolAbril,
I've now added the static language switcher using languages.json, and the dynamic version dropdown using versions.json.
Could you please verify ??

[OriolAbril]

Thanks! I will try to review before the meeting tomorrow but there is high probability I won't be able. The video looks good and the modified lines summary of +167 −48 looks very promising too

[aterrel]

Accepting this PR at the moment seems to make it so the live site will be pushing a switcher that goes to a 404. Can we fix that first?

[OriolAbril]

Even if we fixed this I don't think it is ready to merge yet

[AR21SM]

Hi @OriolAbril, when you get a chance, could you please review this? I believe I’ve addressed all your feedback and implemented the changes as discussed in proposal #334

[AR21SM]

Hi @OriolAbril Could you please verify ??

[OriolAbril]

Looking great already, we have to coordinate in the next meeting to see how to "backport" part of these changes to 1.0 and 2.0 branches

[aterrel]

I created a next branch so we can accept this without causing problems with the current workflow. https://github.com/numfocus/DISCOVER-Cookbook/tree/next

[OriolAbril]

comments are so we can merge this and start backporting elements of this PR into the other versions.

[AR21SM]

Hi, @OriolAbril can you verify ?

[AR21SM]

Hi @aterrel , Could you please add the next branch in Netlify so PR previews work for it too? 😊

[AR21SM]

Previously

Screen.Recording.2025-08-05.185854.mp4

Now

Screen.Recording.2025-08-05.185351.mp4

[OriolAbril]

@AR21SM you have to undo this commit fix: correct English URL structure in language switcher. There will be nothing at url/<version>/, the english version will be at url/<version>/en. Using sphinx-build -b html DISCOVER/ DISCOVER/_build/html/en in the bash script and then publishing DISCOVER/_build/html as is takes care of keeping the en/ folder instead of having the english version at the version root.

[OriolAbril]

The styling is a good start, we can continue polishing in follow up PRs. If you want to open an issue or a discussion to get an idea/proposal on what we want to happen do not hesitate to do so then tag us. In my opinion, we should try to match the look and behaviour of https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html as much as possible (we are using the compontent from the theme, but using a different theme, so it has many differences even if the core javascript to change the urls to matching ones is the same).

[OriolAbril]

There will be nothing at this url given the current pipeline. I would propose using https://discover-cookbook.numfocus.org/versions.json and copying the json into that path but only when deploying from main/next. Otherwise use https://discover-cookbook.numfocus.org/dev/en/_static/versions.json which will already exist.

Having these jsons inside _static could be a bit confusing because the static folder is copied for every build. That is url/dev/es/ will also have the _static folder with the two jsons, same for url/2.0/en/

[AR21SM]

Screen.Recording.2025-08-05.204644.mp4

currently, it looks like this. I was thinking , should I reduce the font size (and box size) a bit and maybe add a little margin between the two buttons? Also, it’s placed at the left corner .Do you think that’s fine, or should I move it to the right or somewhere else? Open to any suggestions.