Skip to content

Commit 2aeea6f

Browse files
authored
Build: disable Sphinx manipulation (#11441)
* 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 * Build: add `READTHEDOCS_REPOSITORY_PATH` environment variable This is a useful variable that we will require during the deprecation of the Sphinx context manipulation. Besides, it seems a useful variable that we should expose to users anyways so they can use it as relative to calculate other useful paths. * Build: add `READTHEDOCS_PRODUCTION_DOMAIN` as environment variable * Document `READTHEDOCS_PRODUCTION_DOMAIN` env var * Update tests
1 parent 8401ea6 commit 2aeea6f

File tree

6 files changed

+56
-19
lines changed

6 files changed

+56
-19
lines changed

docs/user/reference/environment-variables.rst

+17
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,17 @@ All :doc:`build processes </builds>` have the following environment variables au
99

1010
:Default: ``True``
1111

12+
.. envvar:: READTHEDOCS_PRODUCTION_DOMAIN
13+
14+
Domain where Read the Docs application/dashboard and API are running.
15+
16+
:Example: ``readthedocs.org``
17+
:Example: ``readthedocs.com``
18+
:Example: ``app.readthedocs.org``
19+
:Example: ``app.readthedocs.com``
20+
:Example: ``devthedocs.org``
21+
:Example: ``devthedocs.com``
22+
1223
.. envvar:: READTHEDOCS_PROJECT
1324

1425
The :term:`slug` of the project being built. For example, ``my-example-project``.
@@ -81,6 +92,12 @@ All :doc:`build processes </builds>` have the following environment variables au
8192
:Example: ``https://docs.readthedocs.io/ja/stable/``
8293
:Example: ``https://example--17.org.readthedocs.build/fr/17/``
8394

95+
.. envvar:: READTHEDOCS_REPOSITORY_PATH
96+
97+
Path where the repository was cloned.
98+
99+
:Example: ``/home/docs/checkouts/readthedocs.org/user_builds/test-builds/checkouts/latest``
100+
84101
.. envvar:: READTHEDOCS_GIT_CLONE_URL
85102

86103
URL for the remote source repository, from which the documentation is cloned.

readthedocs/doc_builder/backends/sphinx.py

+13-12
Original file line numberDiff line numberDiff line change
@@ -264,20 +264,21 @@ def append_conf(self):
264264
},
265265
)
266266

267-
# Allow symlinks, but only the ones that resolve inside the base directory.
268-
# NOTE: if something goes wrong,
269-
# `safe_open` raises an exception that's clearly communicated to the user.
270-
outfile = safe_open(
271-
self.config_file, "a", allow_symlinks=True, base_path=self.project_path
272-
)
267+
if not self.project.has_feature(Feature.DISABLE_SPHINX_MANIPULATION):
268+
# Allow symlinks, but only the ones that resolve inside the base directory.
269+
# NOTE: if something goes wrong,
270+
# `safe_open` raises an exception that's clearly communicated to the user.
271+
outfile = safe_open(
272+
self.config_file, "a", allow_symlinks=True, base_path=self.project_path
273+
)
273274

274-
# Append config to project conf file
275-
tmpl = template_loader.get_template("doc_builder/conf.py.tmpl")
276-
rendered = tmpl.render(self.get_config_params())
275+
# Append config to project conf file
276+
tmpl = template_loader.get_template("doc_builder/conf.py.tmpl")
277+
rendered = tmpl.render(self.get_config_params())
277278

278-
with outfile:
279-
outfile.write("\n")
280-
outfile.write(rendered)
279+
with outfile:
280+
outfile.write("\n")
281+
outfile.write(rendered)
281282

282283
# Print the contents of conf.py in order to make the rendered
283284
# configfile visible in the build logs

readthedocs/doc_builder/director.py

+9
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
from readthedocs.doc_builder.python_environments import Conda, Virtualenv
2626
from readthedocs.projects.constants import BUILD_COMMANDS_OUTPUT_PATH_HTML
2727
from readthedocs.projects.exceptions import RepositoryError
28+
from readthedocs.projects.models import Feature
2829
from readthedocs.projects.signals import after_build, before_build, before_vcs
2930
from readthedocs.storage import build_tools_storage
3031

@@ -200,6 +201,10 @@ def build(self):
200201
self.run_build_job("post_build")
201202
self.store_readthedocs_build_yaml()
202203

204+
if self.data.project.has_feature(Feature.DISABLE_SPHINX_MANIPULATION):
205+
# Mark this version to inject the new js client when serving it via El Proxito
206+
self.data.version.addons = True
207+
203208
after_build.send(
204209
sender=self.data.version,
205210
)
@@ -645,6 +650,9 @@ def get_rtd_env_vars(self):
645650
"READTHEDOCS_VERSION_NAME": self.data.version.verbose_name,
646651
"READTHEDOCS_PROJECT": self.data.project.slug,
647652
"READTHEDOCS_LANGUAGE": self.data.project.language,
653+
"READTHEDOCS_REPOSITORY_PATH": self.data.project.checkout_path(
654+
self.data.version.slug
655+
),
648656
"READTHEDOCS_OUTPUT": os.path.join(
649657
self.data.project.checkout_path(self.data.version.slug), "_readthedocs/"
650658
),
@@ -654,6 +662,7 @@ def get_rtd_env_vars(self):
654662
# "READTHEDOCS_GIT_HTML_URL": self.data.project.remote_repository.html_url,
655663
"READTHEDOCS_GIT_IDENTIFIER": self.data.version.identifier,
656664
"READTHEDOCS_GIT_COMMIT_HASH": self.data.build["commit"],
665+
"READTHEDOCS_PRODUCTION_DOMAIN": settings.PRODUCTION_DOMAIN,
657666
}
658667
return env
659668

readthedocs/doc_builder/python_environments.py

+5-6
Original file line numberDiff line numberDiff line change
@@ -174,12 +174,11 @@ def _install_latest_requirements(self, pip_install_cmd):
174174
if self.config.doctype == "mkdocs":
175175
requirements.append("mkdocs")
176176
else:
177-
requirements.extend(
178-
[
179-
"sphinx",
180-
"readthedocs-sphinx-ext",
181-
]
182-
)
177+
requirements.append("sphinx")
178+
179+
# Install ``readthedocs-sphinx-ext`` only on old projects
180+
if not self.project.has_feature(Feature.DISABLE_SPHINX_MANIPULATION):
181+
requirements.append("readthedocs-sphinx-ext")
183182

184183
cmd = copy.copy(pip_install_cmd)
185184
cmd.extend(requirements)

readthedocs/projects/models.py

+8-1
Original file line numberDiff line numberDiff line change
@@ -1896,6 +1896,7 @@ def add_features(sender, **kwargs):
18961896
DONT_INSTALL_LATEST_PIP = "dont_install_latest_pip"
18971897
USE_SPHINX_RTD_EXT_LATEST = "rtd_sphinx_ext_latest"
18981898
INSTALL_LATEST_CORE_REQUIREMENTS = "install_latest_core_requirements"
1899+
DISABLE_SPHINX_MANIPULATION = "disable_sphinx_manipulation"
18991900

19001901
# Search related features
19011902
DISABLE_SERVER_SIDE_SEARCH = "disable_server_side_search"
@@ -1973,6 +1974,12 @@ def add_features(sender, **kwargs):
19731974
"Build: Install all the latest versions of Read the Docs core requirements"
19741975
),
19751976
),
1977+
(
1978+
DISABLE_SPHINX_MANIPULATION,
1979+
_(
1980+
"Sphinx: Don't append `conf.py` and don't install ``readthedocs-sphinx-ext``"
1981+
),
1982+
),
19761983
# Search related features.
19771984
(
19781985
DISABLE_SERVER_SIDE_SEARCH,
@@ -2033,7 +2040,7 @@ def get_feature_display(self):
20332040
Because the field is not a ChoiceField here, we need to manually
20342041
implement this behavior.
20352042
"""
2036-
return dict(self.FEATURES).get(self.feature_id, self.feature_id)
2043+
return str(dict(self.FEATURES).get(self.feature_id, self.feature_id))
20372044

20382045

20392046
class EnvironmentVariable(TimeStampedModel, models.Model):

readthedocs/projects/tests/test_build_tasks.py

+4
Original file line numberDiff line numberDiff line change
@@ -361,12 +361,16 @@ def test_get_env_vars(self, load_yaml_config, build_environment, config, externa
361361
"READTHEDOCS_VERSION_NAME": self.version.verbose_name,
362362
"READTHEDOCS_PROJECT": self.project.slug,
363363
"READTHEDOCS_LANGUAGE": self.project.language,
364+
"READTHEDOCS_REPOSITORY_PATH": os.path.join(
365+
self.project.checkout_path(self.version.slug),
366+
),
364367
"READTHEDOCS_OUTPUT": os.path.join(
365368
self.project.checkout_path(self.version.slug), "_readthedocs/"
366369
),
367370
"READTHEDOCS_GIT_CLONE_URL": self.project.repo,
368371
"READTHEDOCS_GIT_IDENTIFIER": self.version.identifier,
369372
"READTHEDOCS_GIT_COMMIT_HASH": self.build.commit,
373+
"READTHEDOCS_PRODUCTION_DOMAIN": settings.PRODUCTION_DOMAIN,
370374
}
371375

372376
self._trigger_update_docs_task()

0 commit comments

Comments
 (0)