Automatically create docs PR on release (#1965)

* Adding auto switcher bump, sending main branch docs to dev

* Use auto commit action to push switcher.json updates

* Adding switcher update script

* Using custom commit message

* Point latest to actually latest version

* Use PR instead of directly pushing to main

* Refine comment

* Use auto-commits

* Remove unused permissions

* Remove obsolete token

* Setup permission, only run on release

* Create PR with updated switcher.json

* Format with stock black

* Update .github/workflows/deploy-docs.yml

* Update .github/workflows/deploy-docs.yml

---------

Co-authored-by: Frank Anema <[email protected]>

Author: merschformann

.github/workflows/deploy-docs.yml

@@ -9,13 +9,20 @@ on:
     types:
       - published
 
+permissions:
+  # Give the GITHUB_TOKEN write permission to open a PR with the changes to the switcher.json file.
+  contents: write
+  pull-requests: write
+
 jobs:
   run:
     runs-on: ubuntu-latest
+
     steps:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0
+        ref: main
 
     - name: Setup Micromamba env
       uses: mamba-org/setup-micromamba@v1
@@ -38,13 +45,29 @@ jobs:
         make clean html linkcheck
         popd
 
+    - name: Update switcher and latest version
+      if: ${{ github.event_name == 'release' }}
+      run: |
+        python docs/update_switcher.py --version ${{ github.ref_name }}
+
+    - name: Create PR
+      if: ${{ github.event_name == 'release' }}
+      uses: peter-evans/create-pull-request@v3
+      with:
+        commit-message: "docs: Update switcher.json for ${{ github.ref_name }}"
+        title: "docs: Update switcher.json for ${{ github.ref_name }}"
+        body: "This PR updates the switcher.json file."
+        branch: "docs/update-switcher-${{ github.ref_name }}"
+        base: "main"
+        labels: "documentation"
+
     - name: Publish to Github Pages on main
       if: ${{ github.ref == 'refs/heads/main' }}
       uses: peaceiris/actions-gh-pages@v4
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_dir: docs/_build/html/
-        destination_dir: latest
+        destination_dir: dev
         keep_files: false
 
     - name: Publish to Github Pages on release

docs/_static/switcher.json

@@ -1,7 +1,11 @@
 [
+  {
+    "version": "dev",
+    "url": "https://python-visualization.github.io/folium/dev/"
+  },
   {
     "version": "latest",
-    "url": "https://python-visualization.github.io/folium/latest/"
+    "url": "https://python-visualization.github.io/folium/v0.16.0/"
   },
   {
     "version": "v0.16.0",

docs/conf.py

@@ -108,8 +108,8 @@
 # documentation.
 html_theme_options = {
     "switcher": {
-        "json_url": "https://python-visualization.github.io/folium/latest/_static/switcher.json",
-        "version_match": "latest" if ".dev" in version else version,
+        "json_url": "https://python-visualization.github.io/folium/dev/_static/switcher.json",
+        "version_match": "dev" if ".dev" in version else version,
     },
     "navbar_start": ["navbar-logo", "version-switcher"],
     "footer_start": ["version", "copyright", "sphinx-version", "theme-version"],

docs/update_switcher.py

@@ -0,0 +1,56 @@
+"""
+This script is used to update switcher.json on docs releases. It adds the new version to
+the list of versions and sets the latest version to the new version.
+"""
+
+import argparse
+import json
+import os
+
+
+def main():
+    # Define CLI arguments
+    parser = argparse.ArgumentParser(description="Update switcher.json")
+    parser.add_argument(
+        "--version", "-v", required=True, type=str, help="The new version to add"
+    )
+    args = parser.parse_args()
+
+    # Setup path to switcher.json (relative to this script) and load it
+    switcher_path = os.path.join(os.path.dirname(__file__), "_static", "switcher.json")
+    with open(switcher_path) as f:
+        switcher = json.load(f)
+
+    # Find index of 'latest' entry
+    latest_index = None
+    for i, version in enumerate(switcher):
+        if version["version"] == "latest":
+            latest_index = i
+            break
+    if latest_index is None:
+        raise ValueError("'latest' version not found in switcher.json")
+
+    # Add the new version to the list of versions (we always insert it after latest)
+    new_version = {
+        "version": args.version,
+        "url": f"https://python-visualization.github.io/folium/{args.version}/",
+    }
+
+    # Update the latest version
+    switcher[latest_index]["url"] = new_version["url"]
+
+    # Make sure version is unique
+    if any(version["version"] == args.version for version in switcher):
+        print(
+            f"Version {args.version} already exists in switcher.json. Not adding it again."
+        )
+    else:
+        switcher.insert(latest_index + 1, new_version)
+
+    # Write the updated switcher.json
+    with open(switcher_path, "w") as f:
+        json.dump(switcher, f, indent=2)
+
+
+if __name__ == "__main__":
+    main()