Build: Add Miniforge3 support to replace deprecated Mambaforge

docs/user/config-file/v2.rst

@@ -327,6 +327,9 @@ You can use several interpreters and versions, from CPython, Miniconda, and Mamb
   - ``mambaforge-22.9``
   - ``mambaforge-23.11``
   - ``mambaforge-latest`` (alias for the latest version available on Read the Docs)
+  - ``miniforge3-24.11``
+  - ``miniforge3-25.1``
+  - ``miniforge3-latest`` (alias for the latest version available on Read the Docs)
 
 build.tools.nodejs
 ``````````````````

readthedocs/builds/constants_docker.py

@@ -46,6 +46,8 @@
             "mambaforge-4.10": "mambaforge-4.10.3-10",
             "mambaforge-22.9": "mambaforge-22.9.0-3",
             "mambaforge-23.11": "mambaforge-23.11.0-0",
+            "miniforge3-24.11": "miniforge3-24.11.2-1",
+            "miniforge3-25.1": "miniforge3-25.1.1-2",
         },
         "nodejs": {
             "14": "14.21.3",
@@ -98,6 +100,7 @@
 _TOOLS["python"]["latest"] = _TOOLS["python"]["3"]
 _TOOLS["python"]["miniconda-latest"] = _TOOLS["python"]["miniconda3-3.12-24.9"]
 _TOOLS["python"]["mambaforge-latest"] = _TOOLS["python"]["mambaforge-23.11"]
+_TOOLS["python"]["miniforge3-latest"] = _TOOLS["python"]["miniforge3-25.1"]
 _TOOLS["nodejs"]["latest"] = _TOOLS["nodejs"]["24"]
 _TOOLS["ruby"]["latest"] = _TOOLS["ruby"]["3.4"]
 _TOOLS["rust"]["latest"] = _TOOLS["rust"]["1.91"]

readthedocs/config/config.py

@@ -218,7 +218,7 @@ def python_interpreter(self):
         tool = self.build.tools.get("python")
         if tool and tool.version.startswith("mamba"):
             return "mamba"
-        if tool and tool.version.startswith("miniconda"):
+        if tool and (tool.version.startswith("miniconda") or tool.version.startswith("miniforge")):
             return "conda"
         if tool:
             return "python"

readthedocs/config/tests/test_config.py

@@ -335,6 +335,72 @@ def test_conda_key_not_required_for_conda_mamba_when_build_commands(self):
         with does_not_raise(ConfigError):
             build.validate()
 
+    def test_conda_key_required_for_miniforge3(self):
+        build = get_build_config(
+            {
+                "build": {
+                    "os": "ubuntu-22.04",
+                    "tools": {
+                        "python": "miniforge3-24.11",
+                    },
+                },
+            }
+        )
+        with raises(ConfigError) as excinfo:
+            build.validate()
+        assert excinfo.value.message_id == ConfigError.CONDA_KEY_REQUIRED
+        assert excinfo.value.format_values.get("key") == "conda"
+
+    def test_conda_key_not_required_for_miniforge3_when_build_commands(self):
+        build = get_build_config(
+            {
+                "build": {
+                    "os": "ubuntu-22.04",
+                    "tools": {
+                        "python": "miniforge3-25.1",
+                    },
+                    "commands": [
+                        "conda env create --file environment.yml",
+                    ],
+                },
+            }
+        )
+        with does_not_raise(ConfigError):
+            build.validate()
+
+    def test_miniforge3_python_interpreter(self, tmpdir):
+        apply_fs(
+            tmpdir,
+            {
+                "readthedocs.yml": """
+                version: 2
+                build:
+                  os: ubuntu-22.04
+                  tools:
+                    python: miniforge3-24.11
+                conda:
+                  environment: environment.yml
+                """,
+                "environment.yml": "name: test",
+            },
+        )
+        build = get_build_config(
+            {
+                "build": {
+                    "os": "ubuntu-22.04",
+                    "tools": {
+                        "python": "miniforge3-24.11",
+                    },
+                },
+                "conda": {
+                    "environment": "environment.yml",
+                },
+            },
+            source_file=str(tmpdir.join("readthedocs.yml")),
+        )
+        build.validate()
+        assert build.python_interpreter == "conda"
+
     @pytest.mark.parametrize("value", [3, [], "invalid"])
     def test_conda_check_invalid_value(self, value):
         build = get_build_config({"conda": value})

readthedocs/doc_builder/director.py

@@ -10,6 +10,7 @@
 
 import datetime
 import os
+import shlex
 import tarfile
 
 import structlog
@@ -622,17 +623,28 @@ def install_build_tools(self):
                 )
                 # If the tool version selected is not available from the
                 # cache we compile it at build time
-                cmd = [
-                    # TODO: make ``PYTHON_CONFIGURE_OPTS="--enable-shared"``
-                    # environment variable to work here. Note that
-                    # ``self.build_environment.run`` does not support passing
-                    # environment for a particular command:
-                    # https://github.com/readthedocs/readthedocs.org/blob/9d2d1a2/readthedocs/doc_builder/environments.py#L430-L431
-                    "asdf",
-                    "install",
-                    tool,
-                    full_version,
-                ]
+
+                # For miniforge3, unset CONDA_ENVS_PATH and CONDA_DEFAULT_ENV
+                # environment variables to allow proper installation
+                # See https://github.com/readthedocs/readthedocs.org/issues/11690
+                if tool == "python" and full_version.startswith("miniforge3"):
+                    cmd = [
+                        "/bin/sh",
+                        "-c",
+                        f"unset CONDA_ENVS_PATH ; unset CONDA_DEFAULT_ENV ; asdf install {shlex.quote(tool)} {shlex.quote(full_version)}",
+                    ]
+                else:
+                    cmd = [
+                        # TODO: make ``PYTHON_CONFIGURE_OPTS="--enable-shared"``
+                        # environment variable to work here. Note that
+                        # ``self.build_environment.run`` does not support passing
+                        # environment for a particular command:
+                        # https://github.com/readthedocs/readthedocs.org/blob/9d2d1a2/readthedocs/doc_builder/environments.py#L430-L431
+                        "asdf",
+                        "install",
+                        tool,
+                        full_version,
+                    ]
                 self.build_environment.run(
                     *cmd,
                 )

readthedocs/rtd_tests/fixtures/spec/v2/schema.json

@@ -203,7 +203,10 @@
                 "mambaforge-4.10",
                 "mambaforge-22.9",
                 "mambaforge-23.11",
-                "mambaforge-latest"
+                "mambaforge-latest",
+                "miniforge3-24.11",
+                "miniforge3-25.1",
+                "miniforge3-latest"
               ]
             },
             "nodejs": {