Add versioned documentation

They are added under /en/<version>/

This might be helpful, before adding new supported languages.
#1105

Author: ArthurSonzogni

.github/workflows/documentation.yaml

@@ -12,6 +12,10 @@ jobs:
     steps:
       - name: "Checkout repository"
         uses: actions/checkout@v3
+        with:
+          fetch-depth: 0   # Need full history.
+          fetch-tags: true # Need tags.
+
 
       - name: "Install cmake"
         uses: lukka/get-cmake@latest
@@ -30,19 +34,23 @@ jobs:
           sudo apt-get install graphviz;
 
       - name: "Build documentation"
+        run: |
+          ./tools/build_multiversion_doc.sh
+
+      - name: "Build examples"
         run: >
+          mkdir -p multiversion_docs/main/examples;
           mkdir build;
           cd build;
           emcmake cmake ..
           -DCMAKE_BUILD_TYPE=Release
-          -DFTXUI_BUILD_DOCS=ON
+          -DFTXUI_BUILD_DOCS=OFF
           -DFTXUI_BUILD_EXAMPLES=ON
           -DFTXUI_BUILD_TESTS=OFF
           -DFTXUI_BUILD_TESTS_FUZZER=OFF
           -DFTXUI_ENABLE_INSTALL=OFF
           -DFTXUI_DEV_WARNINGS=OFF;
           cmake --build . --target doc;
-          cmake --build . ;
           rsync -amv
           --include='*/'
           --include='*.html'
@@ -52,13 +60,13 @@ jobs:
           --include='*.wasm'
           --exclude='*'
           examples
-          doc/doxygen/html;
+          ../multiversion_docs/main/examples;
 
       - name: "Deploy"
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: build/doc/doxygen/html/
+          publish_dir: multiversion_docs
           enable_jekyll: false
           allow_empty_commit: false
           force_orphan: true

doc/footer.html

@@ -2,16 +2,9 @@
 <!-- start footer part -->
 <!--BEGIN GENERATE_TREEVIEW-->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
-  <ul>
-    $navpath
-    <li class="footer">$generatedby <a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion </li>
-  </ul>
 </div>
 <!--END GENERATE_TREEVIEW-->
 <!--BEGIN !GENERATE_TREEVIEW-->
-<hr class="footer"/><address class="footer"><small>
-$generatedby&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion
-</small></address>
 <!--END !GENERATE_TREEVIEW-->
 </body>
 </html>

tools/build_multiversion_doc.sh

@@ -0,0 +1,114 @@
+#!/bin/bash
+
+set -ex
+
+# Get the list of versions to build.
+VERSIONS="main $(git tag --list 'v*')"
+
+echo "Versions to build: $VERSIONS"
+
+# Create a temporary directory for the build.
+BUILD_DIR=$(mktemp -d)
+ROOT_DIR=$(pwd)
+OUTPUT_DIR="$ROOT_DIR/multiversion_docs"
+rm -rf "$OUTPUT_DIR"
+mkdir -p "$OUTPUT_DIR"
+
+# Build the documentation for each version.
+for VERSION in $VERSIONS; do
+  echo "Building documentation for version $VERSION"
+
+  # Checkout the version.
+  git checkout "$VERSION"
+
+  # Create a build subdirectory for the version.
+  mkdir -p "$BUILD_DIR/$VERSION"
+  cd "$BUILD_DIR/$VERSION"
+
+  # Build the documentation and examples with Emscripten.
+  cmake "$ROOT_DIR" -DFTXUI_BUILD_DOCS=ON -DFTXUI_BUILD_EXAMPLES=ON
+  make doc
+
+  # Check if the documentation was generated.
+  if [ ! -d "doc/doxygen/html" ]; then
+    echo "Error: Doxygen documentation not found for version $VERSION"
+    exit 1
+  fi
+
+  # Move the generated documentation to the output directory.
+  mkdir -p "$OUTPUT_DIR/en/$VERSION"
+  mv doc/doxygen/html/* "$OUTPUT_DIR/en/$VERSION/"
+
+  # Move the generated examples to the output directory.
+  mkdir -p "$OUTPUT_DIR/en/$VERSION/examples"
+  mv examples/* "$OUTPUT_DIR/en/$VERSION/examples/"
+
+  cd "$ROOT_DIR"
+done
+
+# Clean up the build directory.
+rm -rf "$BUILD_DIR"
+
+VERSIONS_IN_JS="$(echo $VERSIONS | sed "s/ /', '/g")"
+
+# Inject the version switcher into the documentation.
+for VERSION in $VERSIONS; do
+  cat > "$OUTPUT_DIR/en/$VERSION/version-switcher.js" <<EOL
+document.addEventListener('DOMContentLoaded', function() {
+  const projectNumber = document.getElementById('projectnumber');
+  if (!projectNumber) {
+    return;
+  }
+
+  const version = '$VERSION';
+  const versions = ['$VERSIONS_IN_JS'];
+
+  // Sort the versions in descending order (latest first)
+  versions.sort((a, b) => {
+    if (a === 'main') return -1;
+    if (b === 'main') return 1;
+    return b.localeCompare(a, undefined, { numeric: true, sensitivity: 'base' });
+  });
+
+  const select = document.createElement('select');
+  select.onchange = function() {
+    // Replace `version` by the selected version in the URL.
+    const selectedVersion = this.value;
+    const currentUrl = window.location.href;
+    const newUrl = currentUrl.replace(/$version/.*, selectedVersion);
+
+    // Navigate to the new URL.
+    window.location = newUrl;
+  };
+
+  for (const v of versions) {
+    const option = document.createElement('option');
+    option.value = v;
+    option.text = v;
+    if (v === version) {
+      option.selected = true;
+    }
+    select.appendChild(option);
+  }
+
+  projectNumber.replaceWith(select);
+
+  // Style to blend in with the existing theme.
+  select.style.backgroundColor = 'rgba(0, 0, 0, 0.8)';
+  select.style.color = 'white';
+  select.style.border = '1px solid rgba(255, 255, 255, 0.2)';
+  select.style.padding = '5px';
+  select.style.borderRadius = '5px';
+  select.style.fontSize = '14px';
+  select.style.fontFamily = 'inherit';
+  select.style.marginLeft = '10px';
+  select.style.cursor = 'pointer';
+  });
+EOL
+
+  # Inject the script into all HTML files.
+  find "$OUTPUT_DIR/en/$VERSION/" -name "*.html" -exec sed -i 's|</body>|<script src="version-switcher.js"></script></body>|' {} +
+done
+
+echo "Multi-version documentation generated successfully in $OUTPUT_DIR"
+git checkout main