Build: disable Sphinx manipulation

Add a feature flag called `DISABLE_SPHINX_MANIPULATION` that:

- don't install `readthedocs-sphinx-ext` Python package
- don't append anything to the Sphinx's `conf.py` file
- enable Read the Docs Addons on these versions automatically

The idea behind this is start defaulting new projects to Read the Docs Addons
without breaking old projects.

This is a potential first step in favor of the full deprecation/removal of the
Sphinx manipulation (as we already did for MkDocs). Once this
happens, **building on Read the Docs will produce the exact same result than
building locally**.

Related readthedocs/addons#72

readthedocs/doc_builder/backends/sphinx.py

@@ -264,20 +264,21 @@ def append_conf(self):
                 },
             )
 
-        # Allow symlinks, but only the ones that resolve inside the base directory.
-        # NOTE: if something goes wrong,
-        # `safe_open` raises an exception that's clearly communicated to the user.
-        outfile = safe_open(
-            self.config_file, "a", allow_symlinks=True, base_path=self.project_path
-        )
+        if not self.project.has_feature(Feature.DISABLE_SPHINX_MANIPULATION):
+            # Allow symlinks, but only the ones that resolve inside the base directory.
+            # NOTE: if something goes wrong,
+            # `safe_open` raises an exception that's clearly communicated to the user.
+            outfile = safe_open(
+                self.config_file, "a", allow_symlinks=True, base_path=self.project_path
+            )
 
-        # Append config to project conf file
-        tmpl = template_loader.get_template("doc_builder/conf.py.tmpl")
-        rendered = tmpl.render(self.get_config_params())
+            # Append config to project conf file
+            tmpl = template_loader.get_template("doc_builder/conf.py.tmpl")
+            rendered = tmpl.render(self.get_config_params())
 
-        with outfile:
-            outfile.write("\n")
-            outfile.write(rendered)
+            with outfile:
+                outfile.write("\n")
+                outfile.write(rendered)
 
         # Print the contents of conf.py in order to make the rendered
         # configfile visible in the build logs

readthedocs/doc_builder/director.py

@@ -25,6 +25,7 @@
 from readthedocs.doc_builder.python_environments import Conda, Virtualenv
 from readthedocs.projects.constants import BUILD_COMMANDS_OUTPUT_PATH_HTML
 from readthedocs.projects.exceptions import RepositoryError
+from readthedocs.projects.models import Feature
 from readthedocs.projects.signals import after_build, before_build, before_vcs
 from readthedocs.storage import build_tools_storage
 
@@ -200,6 +201,10 @@ def build(self):
         self.run_build_job("post_build")
         self.store_readthedocs_build_yaml()
 
+        if self.data.project.has_feature(Feature.DISABLE_SPHINX_MANIPULATION):
+            # Mark this version to inject the new js client when serving it via El Proxito
+            self.data.version.addons = True
+
         after_build.send(
             sender=self.data.version,
         )

readthedocs/doc_builder/python_environments.py

@@ -174,12 +174,11 @@ def _install_latest_requirements(self, pip_install_cmd):
         if self.config.doctype == "mkdocs":
             requirements.append("mkdocs")
         else:
-            requirements.extend(
-                [
-                    "sphinx",
-                    "readthedocs-sphinx-ext",
-                ]
-            )
+            requirements.append("sphinx")
+
+            # Install ``readthedocs-sphinx-ext`` only on old projects
+            if not self.project.has_feature(Feature.DISABLE_SPHINX_MANIPULATION):
+                requirements.append("readthedocs-sphinx-ext")
 
         cmd = copy.copy(pip_install_cmd)
         cmd.extend(requirements)

readthedocs/projects/models.py

@@ -1896,6 +1896,7 @@ def add_features(sender, **kwargs):
     DONT_INSTALL_LATEST_PIP = "dont_install_latest_pip"
     USE_SPHINX_RTD_EXT_LATEST = "rtd_sphinx_ext_latest"
     INSTALL_LATEST_CORE_REQUIREMENTS = "install_latest_core_requirements"
+    DISABLE_SPHINX_MANIPULATION = "disable_sphinx_manipulation"
 
     # Search related features
     DISABLE_SERVER_SIDE_SEARCH = "disable_server_side_search"
@@ -1973,6 +1974,12 @@ def add_features(sender, **kwargs):
                 "Build: Install all the latest versions of Read the Docs core requirements"
             ),
         ),
+        (
+            DISABLE_SPHINX_MANIPULATION,
+            _(
+                "Sphinx: Don't append `conf.py` and don't install ``readthedocs-sphinx-ext``"
+            ),
+        ),
         # Search related features.
         (
             DISABLE_SERVER_SIDE_SEARCH,
@@ -2033,7 +2040,7 @@ def get_feature_display(self):
         Because the field is not a ChoiceField here, we need to manually
         implement this behavior.
         """
-        return dict(self.FEATURES).get(self.feature_id, self.feature_id)
+        return str(dict(self.FEATURES).get(self.feature_id, self.feature_id))
 
 
 class EnvironmentVariable(TimeStampedModel, models.Model):