docs: Deploy documentation artifacts to S3 (#745)

- Replace the use of `gh-pages` by S3 bucket: the commits history
remains light and clean,
- Create a new version of the documentation after each release of
`skore`,
- Add a drop-down list allowing user to select the last 10 versions (+
`dev`) of the documentation of `skore`,
- Running locally `make html` build documentation with a `dev` tag.

---

After each __commit__ on the `main` branch, the documentation is build
and deployed on the `S3:dev/` directory.
After each __release__, the documentation is build and deployed to the
`S3:version/` directory, the version being
a subpart of the tag `MAJOR.MINOR.BUGFIX`: `MAJOR.MINOR`.
For instance, with the following timeline:
```
       dev/ dev/ dev/ dev/ dev/                                                                                  
       0.1/                0.2/                                                                                  
main -- x -- x -- x -- x -- x -- >                                                                               
        |                   |                                                                                    
tag    0.1                 0.2       
```
The S3 bucket looks like:
```
    .                                                                                                            
    ├── 0.1/                                                                                                     
    ├── 0.2/                                                                                                     
    ├── dev/                                                                                                     
    ├── index.html                                                                                               
    └── versions.json
```

.github/actions/sphinx/build/action.yml

@@ -1,4 +1,11 @@
 name: Build sphinx documentation
+
+inputs:
+  SPHINX_VERSION:
+    required: true
+  SPHINX_RELEASE:
+    required: true
+
 runs:
   using: composite
   steps:
@@ -9,4 +16,7 @@ runs:
         python -m pip install '.[sphinx]'
     - working-directory: sphinx
       shell: bash
-      run: make html
+      run: >
+        SPHINX_VERSION=${{ inputs.SPHINX_VERSION }}
+        SPHINX_RELEASE=${{ inputs.SPHINX_RELEASE }}
+        make html

.github/actions/sphinx/deploy/action.yml

@@ -1,19 +1,38 @@
 name: Deploy sphinx documentation
-permissions:
-  contents: write
+
+inputs:
+  CONFIGURATION:
+    required: true
+  ACTION:
+    required: false
+    default: sync
+    type: choice
+    options:
+      - copy
+      - sync
+  PROVIDER:
+    required: false
+    default: scaleway
+  BUCKET:
+    required: false
+    default: prod-probabl-skore
+  SOURCE:
+    required: true
+  DESTINATION:
+    required: true
+
 runs:
   using: composite
   steps:
     - shell: bash
       run: |
-        rm -rf docs/latest
-        mv sphinx/build/html docs/latest
+        sudo apt-get update
+        sudo apt-get install -y rclone
+    - shell: bash
+      run: echo "${{ inputs.CONFIGURATION }}" > rclone.configuration
     - shell: bash
       run: |
-        git config user.name 'github-actions[bot]'
-        git config user.email 'github-actions[bot]@users.noreply.github.com'
-        git config commit.cleanup 'verbatim'
-
-        git add docs/latest
-        git commit -m $'docs: Build documentation triggered by ${{ github.sha }}\n\n\nskip-checks:true'
-        git push
+        rclone --config rclone.configuration \
+               ${{ inputs.ACTION }} \
+               ${{ inputs.SOURCE }} \
+               ${{ inputs.PROVIDER }}:${{ inputs.BUCKET }}/${{ inputs.DESTINATION }}

.github/workflows/sphinx.yml

@@ -1,5 +1,51 @@
 name: Sphinx
 
+
+# **How it works**
+# ================
+#
+# After each __commit__ on the `main` branch, the documentation is built and deployed on the `S3:dev/` directory.
+# After each __release__, the documentation is built and deployed to the `S3:version/` directory, the version being
+# a subpart of the tag `MAJOR.MINOR.BUGFIX`: `MAJOR.MINOR`.
+#
+# For instance, with the following timeline:
+#
+#        dev/ dev/ dev/ dev/ dev/
+#        0.1/                0.2/
+# main -- x -- x -- x -- x -- x -- >
+#         |                   |
+# tag    0.1                 0.2
+#
+# The S3 bucket looks like:
+#     .
+#     ├── 0.1/
+#     ├── 0.2/
+#     ├── dev/
+#     ├── index.html
+#     └── versions.json
+#
+# **Q&A**
+# =======
+#
+# ### `dev/`, why?
+# It contains the most up-to-date documentation, i.e. the documentation of code that is not released but committed on the main branch.
+#
+# ### Version the documentation on `MAJOR.MINOR, why not on `MAJOR`?
+# Currently, we add new features at a minor level. This way, we can separate documentation between two features.
+#
+# ### Only on release (not on release-candidate), why?
+# The release-candidates are documented in the `dev/` directory. We don't want to create noise with explicit directory for such tags.
+#
+# ### How to change an old version of the documentation?
+# You can create tags wherever you want, i.e. on separate branches.
+# For example, you can create a branch from an old tag (`0.1.5`), modify the documentation and create a new tag (`0.1.6`).
+# The corresponding documentation will be automatically updated (`0.1`).
+#
+# **Side-notes**
+# ==============
+#
+# Only the 10 latest versions are listed in sphinx version-switcher to avoid overloading, but the bucket remains unchanged.
+
 on:
   pull_request:
     paths:
@@ -17,22 +63,131 @@ on:
       - 'examples/**'
       - 'sphinx/**'
       - 'skore/**'
+  release:
+    types: [released]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  sphinx:
+  sphinx-version:
     runs-on: ubuntu-latest
+    outputs:
+      SPHINX_VERSION: ${{ steps.sphinx-version.outputs.SPHINX_VERSION }}
+      SPHINX_RELEASE: ${{ steps.sphinx-version.outputs.SPHINX_RELEASE }}
+    steps:
+      - shell: bash
+        id: sphinx-version
+        run: |
+          set -u
+
+          if [[ "${GITHUB_EVENT_NAME}" != "release" ]]; then
+              echo "SPHINX_VERSION=dev" >> "${GITHUB_OUTPUT}"
+              echo "SPHINX_RELEASE=0.0.0+dev" >> "${GITHUB_OUTPUT}"
+              exit 0
+          fi
+
+          set -e
+
+          if [[ "${GITHUB_REF_NAME}" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)?$ ]]; then
+              echo "SPHINX_VERSION=${BASH_REMATCH[1]}.${BASH_REMATCH[2]}" >> "${GITHUB_OUTPUT}"
+              echo "SPHINX_RELEASE=${GITHUB_REF_NAME}" >> "${GITHUB_OUTPUT}"
+          fi
+
+  sphinx-build:
+    runs-on: ubuntu-latest
+    needs: sphinx-version
     steps:
       - uses: actions/checkout@v4
-        with:
-          ssh-key: ${{ secrets.DEPLOY_KEY }}
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'
           cache: 'pip'
       - uses: ./.github/actions/sphinx/build
-      - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-        uses: ./.github/actions/sphinx/deploy
+        with:
+          SPHINX_VERSION: ${{ needs.sphinx-version.outputs.SPHINX_VERSION }}
+          SPHINX_RELEASE: ${{ needs.sphinx-version.outputs.SPHINX_RELEASE }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sphinx-html-artifact
+          path: sphinx/build/html/
+
+  sphinx-deploy-html:
+    runs-on: ubuntu-latest
+    if: ${{ (github.event_name == 'release') || (github.event_name == 'push' && github.ref == 'refs/heads/main') }}
+    needs: [sphinx-version, sphinx-build]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: sphinx-html-artifact
+          path: html/
+      - uses: ./.github/actions/sphinx/deploy
+        with:
+          CONFIGURATION: ${{ secrets.RCLONE_CONFIG_DOCS }}
+          SOURCE: html/
+          DESTINATION: ${{ needs.sphinx-version.outputs.SPHINX_VERSION }}/
+
+  sphinx-deploy-root-files:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'release' }}
+    needs: [sphinx-version, sphinx-build, sphinx-deploy-html]
+    steps:
+      - uses: actions/checkout@v4
+      - shell: python
+        run: |
+            import os
+            import requests
+            import operator
+            import json
+
+            url = "https://skore.probabl.ai"
+            current = os.environ["CURRENT"]
+
+            response = requests.get(f"{url}/versions.json")
+            response.raise_for_status()
+
+            history = set(map(operator.itemgetter("version"), response.json())) - {"dev"} | {current}
+            history = sorted(history, key=lambda x: float(x), reverse=True)[:10]
+
+            new = [
+                {
+                    "name": version,
+                    "version": version,
+                    "url": f"{url}/{version}/",
+                    "preferred": i == 1,
+                }
+                for i, version in enumerate(["dev"] + history)
+            ]
+
+            os.mkdir("artifacts")
+
+            with open("artifacts/versions.json", "w", encoding="utf-8") as file:
+                json.dump(new, file, ensure_ascii=False, indent=4)
+
+            with open("artifacts/index.html", "w", encoding="utf-8") as file:
+              file.write(
+                  f"""
+                  <head>
+                    <meta http-equiv=\"refresh\" content=\"0; url={new[1]["url"]}\"/>
+                  </head>
+                  """
+              )
+        env:
+          CURRENT: ${{ needs.sphinx-version.outputs.SPHINX_VERSION }}
+      - uses: ./.github/actions/sphinx/deploy
+        with:
+          CONFIGURATION: ${{ secrets.RCLONE_CONFIG_DOCS }}
+          ACTION: copy
+          SOURCE: artifacts/
+          DESTINATION:
+
+  sphinx-clean:
+    runs-on: ubuntu-latest
+    if: always()
+    needs: [sphinx-version, sphinx-build, sphinx-deploy-html, sphinx-deploy-root-files]
+    steps:
+      - uses: geekyeggo/delete-artifact@v5
+        with:
+          name: sphinx-html-artifact

docs/latest/_sources/auto_examples/00_getting_started/index.rst.txt

@@ -0,0 +1,47 @@
+
+
+.. _sphx_glr_auto_examples_00_getting_started:
+
+Getting started
+---------------
+
+We recommend first having a look at this example that serves as an overall and gentle
+introduction to skore.
+
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbnails">
+
+.. thumbnail-parent-div-open
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="Getting started with skore">
+
+.. only:: html
+
+  .. image:: /auto_examples/00_getting_started/images/thumb/sphx_glr_plot_01_getting_started_thumb.png
+    :alt:
+
+  :ref:`sphx_glr_auto_examples_00_getting_started_plot_01_getting_started.py`
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">Getting started with skore</div>
+    </div>
+
+
+.. thumbnail-parent-div-close
+
+.. raw:: html
+
+    </div>
+
+
+.. toctree::
+   :hidden:
+
+   /auto_examples/00_getting_started/plot_01_getting_started
+

docs/latest/_sources/auto_examples/01_track/index.rst.txt

@@ -0,0 +1,64 @@
+
+
+.. _sphx_glr_auto_examples_01_track:
+
+Track
+-----
+
+These examples illustrate the skore Project and UI.
+
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbnails">
+
+.. thumbnail-parent-div-open
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="This example provides an overview of the functionalities and the different types of items that we can store in a skore Project.">
+
+.. only:: html
+
+  .. image:: /auto_examples/01_track/images/thumb/sphx_glr_plot_01_overview_skore_project_thumb.png
+    :alt:
+
+  :ref:`sphx_glr_auto_examples_01_track_plot_01_overview_skore_project.py`
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">Overview of the skore project</div>
+    </div>
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="This example illustrates how skore can be used to track some items using their history, for example tracking some ML metrics over time.">
+
+.. only:: html
+
+  .. image:: /auto_examples/01_track/images/thumb/sphx_glr_plot_02_tracking_items_thumb.png
+    :alt:
+
+  :ref:`sphx_glr_auto_examples_01_track_plot_02_tracking_items.py`
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">Tracking items using their history</div>
+    </div>
+
+
+.. thumbnail-parent-div-close
+
+.. raw:: html
+
+    </div>
+
+
+.. toctree::
+   :hidden:
+
+   /auto_examples/01_track/plot_01_overview_skore_project
+   /auto_examples/01_track/plot_02_tracking_items
+