Backport PR #2006: Feat: redirect to RTD if local docs missing (#2006)

* feat: still link Swagger to Sphinx, but use the external RTD stable docs in case local docs are missing (not built)

Signed-off-by: F.N. Claessen <claessen@seita.nl>

* Revert "feat: still link Swagger to Sphinx, but use the external RTD stable docs in case local docs are missing (not built)"

This reverts commit 52565a3.

* feat: redirect to RTD in case of missing local docs (not built)

Signed-off-by: F.N. Claessen <claessen@seita.nl>

* docs: changelog entry

Signed-off-by: F.N. Claessen <claessen@seita.nl>

---------

Signed-off-by: F.N. Claessen <claessen@seita.nl>
(cherry picked from commit b6d44d0)

Author: Flix6x

documentation/changelog.rst

@@ -9,7 +9,7 @@ v0.31.1 | March XX, 2026
 
 Bugfixes
 -----------
-- Add missing field documentation for ``aggregate-power`` and ``state-of-charge`` fields, which can be used to reference a sensor on which to record extra scheduling results [see `PR #2003 <https://www.github.com/FlexMeasures/flexmeasures/pull/2003>`_]
+- Add missing field documentation for ``aggregate-power`` and ``state-of-charge`` fields, which can be used to reference a sensor on which to record extra scheduling results [see `PR #2003 <https://www.github.com/FlexMeasures/flexmeasures/pull/2003>`_ and `PR #2006 <https://www.github.com/FlexMeasures/flexmeasures/pull/2006>`_]
 
 
 v0.31.0 | February 28, 2026

flexmeasures/ui/error_handlers.py

@@ -1,6 +1,6 @@
 """Error views for UI purposes."""
 
-from flask import Flask
+from flask import Flask, request, redirect
 from werkzeug.exceptions import BadRequest, InternalServerError, HTTPException
 
 from flexmeasures.ui.utils.view_utils import render_flexmeasures_template
@@ -60,6 +60,33 @@ def handle_bad_request(e: BadRequest):
 
 
 def handle_not_found(e):
+    """Handle 404 errors for the UI.
+
+    Special handling:
+      - If the request is for documentation under
+        ``/ui/static/documentation/html``, redirect to the
+        corresponding ReadTheDocs URL.
+      - Preserves query string parameters.
+
+    Examples
+    --------
+    /ui/static/documentation/html/index.html
+        -> https://flexmeasures.readthedocs.io/stable/index.html
+
+    /ui/static/documentation/html/search.html?q=commitments
+        -> https://flexmeasures.readthedocs.io/stable/search.html?q=commitments
+    """
+    docs_prefix = "/ui/static/documentation/html"
+
+    if request.path.startswith(docs_prefix):
+        # remove prefix and any leading slash
+        page = request.path[len(docs_prefix) :].lstrip("/")
+        # include query string if present
+        query = f"?{request.query_string.decode()}" if request.query_string else ""
+        return redirect(
+            f"https://flexmeasures.readthedocs.io/stable/{page}{query}", 302
+        )
+
     return (
         render_flexmeasures_template(
             "error.html",