feat: Implement dynamic version dropdown and static language switcher

.github/workflows/build-gh-pages.yml

@@ -5,6 +5,7 @@ on:
   push:
     branches:
     - main
+    - next
 
 # This job installs dependencies, build the book, and pushes it to `gh-pages`
 jobs:
@@ -18,19 +19,14 @@ jobs:
       with:
         python-version: 3.13
 
-    - name: Install dependencies
-      run: |
-        pip install jupyter-book
-        pip install sphinx-tags
-
     - name: Build the book
       run: |
-        rm -rf DISCOVER/_tags/*
-        sphinx-build -b html DISCOVER/ DISCOVER/_build/html
+        bash ci/build_website.sh
 
     - 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

DISCOVER/_static/css/mainLogo.css

@@ -118,4 +118,35 @@ html[data-theme=dark] .social-links a:hover {
   .social-links {
     margin: 1rem 0 0 0;
   }
-}
+}
+
+.version-switcher__button {
+  color: #9ca4af !important;
+}
+.version-switcher__button:hover{
+  color: #ced6dd !important;
+}
+#language-switcher-button {
+  background-color: #121212 !important;
+  border: 1px solid transparent !important;
+}
+
+#language-switcher-button:hover {
+  background-color: #121212 !important;
+  border: 1px solid transparent !important;
+  box-shadow: 0 0 0 0.1875rem #e89217 !important;
+}
+
+#language-switcher-button:focus {
+  background-color: #121212 !important;
+  border: 1px solid transparent !important;
+  box-shadow: 0 0 0 0.1875rem #e89217 !important;
+}
+.dropdown-item.active {
+  background-color:#121212 !important;
+  color: #528fe4 !important;
+}
+.dropdown-item.active:hover {
+  color: #ced6dd !important;
+}
+

DISCOVER/_static/languages.json

@@ -0,0 +1,14 @@
+[
+    {
+        "code": "en",
+        "name_local": "English",
+        "direction": "ltr"
+    },
+    {
+        "code": "es",
+        "name_local": "Español",
+        "direction": "ltr",
+        "hidden": true
+    }
+
+]

DISCOVER/_static/versions.json

@@ -0,0 +1,16 @@
+[
+    {
+        "version": "dev", 
+        "url": "https://discover-cookbook.numfocus.org/dev/"
+    },
+    {
+        "version": "2.0",
+        "url": "https://discover-cookbook.numfocus.org/2.0/",
+        "preferred": true
+    },
+    {
+        "version": "1.0",
+        "url": "https://discover-cookbook.numfocus.org/1.0/"
+    }
+
+]

DISCOVER/_templates/language-switcher.html

@@ -0,0 +1,22 @@
+<div class="dropdown">
+  <button class="btn btn-sm btn-outline-secondary dropdown-toggle" type="button" id="language-switcher-button"
+    data-bs-toggle="dropdown" aria-expanded="false">
+      {{current_language_name}}
+  </button>
+  <ul class="dropdown-menu" aria-labelledby="language-switcher-button">
+    {% for item in languages %}
+        <li>
+          {% if item.code == 'en' %}
+            {% set lang_url = baseurl + "/" + current_version + "/" + pagename + ".html" %}
+          {% else %}
+            {% set lang_url = baseurl + "/" + current_version + "/" + item.code + "/" + pagename + ".html" %}
+          {% endif %}
+          <a class="dropdown-item{% if current_language == item.code %} active{% endif %}" 
+            href="{{ lang_url }}"
+            {% if item.direction %}dir="{{ item.direction }}"{% endif %}>
+            {{ item.name_local }}
+          </a>
+        </li>
+    {% endfor %}
+  </ul>
+</div>

DISCOVER/conf.py

@@ -1,12 +1,37 @@
-###############################################################################
-# Auto-generated by `jupyter-book config`
-# If you wish to continue using _config.yml, make edits to that file and
-# re-generate this one.
-###############################################################################
+version = 'dev'
+language = 'en'
+baseurl = 'https://discover-cookbook.numfocus.org'
+
+import json
+import os
+
+# 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
+}
+
+html_baseurl = baseurl
+
 author = 'Community'
 comments_config = {'hypothesis': False, 'utterances': False}
 copyright = '2023'
-
 exclude_patterns = ['**.ipynb_checkpoints', '.DS_Store', 'Thumbs.db', '_build']
 extensions = ['sphinx_togglebutton', 'sphinx_copybutton', 'myst_nb', 'jupyter_book', 'sphinx_external_toc', 'sphinx.ext.intersphinx', 'sphinx_design', 'sphinx_book_theme', 'sphinx_tags', 'sphinx_jupyterbook_latex', 'sphinx_multitoc_numbering']
 external_toc_exclude_missing = False
@@ -19,7 +44,31 @@
 html_sourcelink_suffix = ''
 html_static_path = ['_static']
 html_theme = 'sphinx_book_theme'
-html_theme_options = {'search_bar_text': 'Search this book...', 'launch_buttons': {'notebook_interface': 'classic', 'binderhub_url': '', 'jupyterhub_url': '', 'thebe': False, 'colab_url': '', 'deepnote_url': ''}, 'path_to_docs': 'DISCOVER', 'repository_url': 'https://github.com/numfocus/DISCOVER-Cookbook/', 'repository_branch': 'main', 'extra_footer': '', 'home_page_in_toc': True, 'announcement': '', 'analytics': {'google_analytics_id': '', 'plausible_analytics_domain': '', 'plausible_analytics_url': 'https://plausible.io/js/script.js'}, 'use_repository_button': True, 'use_edit_page_button': False, 'use_issues_button': True}
+templates_path = ["_templates"]
+html_theme_options = {
+    'search_bar_text': 'Search this book...', 
+    'launch_buttons': {'notebook_interface': 'classic', 'binderhub_url': '', 'jupyterhub_url': '', 'thebe': False, 'colab_url': '', 'deepnote_url': ''}, 
+    'path_to_docs': 'DISCOVER', 
+    'repository_url': 'https://github.com/numfocus/DISCOVER-Cookbook/', 
+    'repository_branch': 'main', 
+    'extra_footer': '', 
+    'home_page_in_toc': True, 
+    'announcement': '', 
+    'analytics': {'google_analytics_id': '', 'plausible_analytics_domain': '', 'plausible_analytics_url': 'https://plausible.io/js/script.js'}, 
+    'use_repository_button': True, 
+    'use_edit_page_button': False, 
+    'use_issues_button': True,
+
+
+    "article_header_start": ["toggle-primary-sidebar","version-switcher","language-switcher"],
+    "navigation_with_keys": False,
+    "show_version_warning_banner": True,
+    "switcher": {
+        "json_url": "https://discover-cookbook.numfocus.org/_static/versions.json", 
+        "version_match": version,
+    },
+}
+
 html_title = 'DISCOVER'
 latex_engine = 'pdflatex'
 myst_enable_extensions = ['colon_fence', 'dollarmath', 'linkify', 'substitution', 'tasklist']

README.md

@@ -24,7 +24,7 @@ While content is the heart of the project, the quality of the content needs to r
 
 ### Bug fixes
 
-For issues with other elements of the book, first make sure an issue is open and tracking can occur on the issue. Then open a a [pull request](https://github.com/numfocus/DISCOVER-Cookbook/pulls).
+For issues with other elements of the book, first make sure an issue is open and tracking can occur on the issue. Then open a [pull request](https://github.com/numfocus/DISCOVER-Cookbook/pulls).
 
 > **Note:** To contribute effectively, check for active pull requests to avoid duplication, discuss your ideas in active issues or pull requests, and seek approval from maintainers or issue creators before proceeding. Respect others' contributions and collaborate constructively to improve the project.
 
@@ -47,7 +47,7 @@ To contribute changes:
 
 4. **Make Changes**: 
    - Edit files in your preferred editor
-   - Build and verify your changes locally using the [build instructions](#how-to-run-the-book-locally) below
+   - See [how to build and run the site locally](#how-to-build-and-run-the-site-locally) below to test your changes.
 
 5. **Test Locally**: Build the book and view your changes:
    ```sh
@@ -72,7 +72,7 @@ To contribute changes:
 See the [contributing.md](CONTRIBUTING.md) for a detailed guide on how to contribute.
 
 
-## How to run the book locally
+## How to Build and Run the Site Locally
 
 Create a local python environment and install all the required dependencies using the following commands (either with conda or pip)
 

ci/build_website.sh

@@ -0,0 +1,23 @@
+
+echo "Starting build process..."
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Clean tags directory
+rm -rf DISCOVER/_tags/*
+
+echo "Building English version..."
+sphinx-build -b html DISCOVER/ DISCOVER/_build/html/en
+
+
+# Copy root level files if they exist
+if [ -f "DISCOVER/_static/404.html" ]; then
+  cp DISCOVER/_static/404.html DISCOVER/_build/html/
+fi
+
+# if [ -f "DISCOVER/_static/index.html" ]; then
+#   cp DISCOVER/_static/index.html DISCOVER/_build/html/
+# fi
+
+echo "Build completed successfully"

netlify.toml

@@ -0,0 +1,6 @@
+[build]
+  publish = "DISCOVER/_build/html"
+  command = "bash ci/build_website.sh"
+
+[build.environment]
+  PYTHON_VERSION = "3.12"