From 9247c9eea57d333624a508c4f1ad241a53064531 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 31 Jul 2023 11:30:21 +0200 Subject: [PATCH] Build: do not auto-create `conf.py` Sphinx file Follows https://blog.readthedocs.com/doctool-without-configuration-file/ --- readthedocs/doc_builder/backends/sphinx.py | 33 +--------- .../rtd_tests/tests/test_doc_builder.py | 60 ------------------- readthedocs/templates/sphinx/conf.py.conf | 28 --------- 3 files changed, 2 insertions(+), 119 deletions(-) delete mode 100644 readthedocs/templates/sphinx/conf.py.conf diff --git a/readthedocs/doc_builder/backends/sphinx.py b/readthedocs/doc_builder/backends/sphinx.py index a9cadd101e8..f7b88ac91e2 100644 --- a/readthedocs/doc_builder/backends/sphinx.py +++ b/readthedocs/doc_builder/backends/sphinx.py @@ -12,7 +12,6 @@ import structlog from django.conf import settings from django.template import loader as template_loader -from django.template.loader import render_to_string from django.urls import reverse from requests.exceptions import ConnectionError @@ -24,7 +23,6 @@ from readthedocs.projects.exceptions import ProjectConfigurationError, UserFileNotFound from readthedocs.projects.models import Feature from readthedocs.projects.templatetags.projects_tags import sort_version_aware -from readthedocs.projects.utils import safe_write from ..base import BaseBuilder from ..constants import PDF_RE @@ -113,25 +111,6 @@ def __init__(self, *args, **kwargs): # because Read the Docs will automatically create one for it. pass - def _write_config(self, master_doc='index'): - """Create ``conf.py`` if it doesn't exist.""" - log.info( - 'Creating default Sphinx config file for project.', - project_slug=self.project.slug, - version_slug=self.version.slug, - ) - docs_dir = self.docs_dir() - conf_template = render_to_string( - 'sphinx/conf.py.conf', - { - 'project': self.project, - 'version': self.version, - 'master_doc': master_doc, - }, - ) - conf_file = os.path.join(docs_dir, 'conf.py') - safe_write(conf_file, conf_template) - def get_config_params(self): """Get configuration parameters to be rendered into the conf file.""" # TODO this should be handled better in the theme @@ -272,18 +251,10 @@ def get_config_params(self): def append_conf(self): """ - Find or create a ``conf.py`` and appends default content. + Find a ``conf.py`` and appends default content. The default content is rendered from ``doc_builder/conf.py.tmpl``. """ - - # Generate a `conf.py` from a template - # - # TODO: we should remove this feature at some point to move forward - # with the idea of remove magic from the builders. - if not self.config_file: - self._write_config() - try: self.config_file = ( self.config_file or self.project.conf_file(self.version.slug) @@ -310,7 +281,7 @@ def append_conf(self): outfile.write(rendered) # Print the contents of conf.py in order to make the rendered - # configfile visible in the build logs + # config file visible in the build logs self.run( 'cat', os.path.relpath( diff --git a/readthedocs/rtd_tests/tests/test_doc_builder.py b/readthedocs/rtd_tests/tests/test_doc_builder.py index b24b0807a00..066c3bc77a5 100644 --- a/readthedocs/rtd_tests/tests/test_doc_builder.py +++ b/readthedocs/rtd_tests/tests/test_doc_builder.py @@ -165,66 +165,6 @@ def test_html_context_only_has_public_versions( } self.assertEqual(versions, {'v1', 'v2'}) - @patch('readthedocs.doc_builder.backends.sphinx.BaseSphinx.docs_dir') - @patch('readthedocs.doc_builder.backends.sphinx.BaseSphinx.get_config_params') - @patch('readthedocs.doc_builder.backends.sphinx.BaseSphinx.run') - @patch('readthedocs.builds.models.Version.get_conf_py_path') - @patch('readthedocs.projects.models.Project.checkout_path') - def test_create_conf_py( - self, - checkout_path, - get_conf_py_path, - _, - get_config_params, - docs_dir, - ): - """ - Test for a project without ``conf.py`` file. - - When this happen, the ``get_conf_py_path`` raises a - ``ProjectConfigurationError`` which is captured by our own code and - generates a conf.py file based using our own template. - - This template should be properly rendered in Python2 and Python3 without - any kind of exception raised by ``append_conf`` (we were originally - having a ``TypeError`` because of an encoding problem in Python3) - """ - tmp_dir = tempfile.mkdtemp() - checkout_path.return_value = tmp_dir - docs_dir.return_value = tmp_dir - get_config_params.return_value = {} - get_conf_py_path.side_effect = ProjectConfigurationError - python_env = Virtualenv( - version=self.version, - build_env=self.build_env, - config=None, - ) - base_sphinx = BaseSphinx( - build_env=self.build_env, - python_env=python_env, - ) - try: - with override_settings(DOCROOT=tmp_dir): - base_sphinx.append_conf() - except Exception: - pytest.fail('Exception was generated when append_conf called.') - - # Check the content generated by our method is the same than what we - # expects from a pre-generated file - generated_conf_py = os.path.join(base_sphinx.docs_dir(), 'conf.py') - expected_conf_py = os.path.join( - os.path.dirname(__file__), - '..', - 'files', - 'conf.py', - ) - with open(generated_conf_py) as gf, open(expected_conf_py) as ef: - autogenerated_confpy_lines = 28 - self.assertEqual( - gf.readlines()[:autogenerated_confpy_lines], - ef.readlines()[:autogenerated_confpy_lines], - ) - @patch('readthedocs.doc_builder.backends.sphinx.BaseSphinx.docs_dir') @patch('readthedocs.doc_builder.backends.sphinx.BaseSphinx.get_config_params') @patch('readthedocs.doc_builder.backends.sphinx.BaseSphinx.run') diff --git a/readthedocs/templates/sphinx/conf.py.conf b/readthedocs/templates/sphinx/conf.py.conf deleted file mode 100644 index 43e7b58b290..00000000000 --- a/readthedocs/templates/sphinx/conf.py.conf +++ /dev/null @@ -1,28 +0,0 @@ -# -*- coding: utf-8 -*- - -from __future__ import division, print_function, unicode_literals - -from datetime import datetime - -from recommonmark.parser import CommonMarkParser - -extensions = [] -templates_path = ['templates', '_templates', '.templates'] -source_suffix = ['.rst', '.md'] -source_parsers = { - '.md': CommonMarkParser, - } -master_doc = 'index' -project = u'{{ project.name }}' -copyright = str(datetime.now().year) -version = '{{ version.verbose_name }}' -release = '{{ version.verbose_name }}' -exclude_patterns = ['_build'] -pygments_style = 'sphinx' -htmlhelp_basename = '{{ project.slug }}' -html_theme = 'sphinx_rtd_theme' -file_insertion_enabled = False -latex_documents = [ - ('index', '{{ project.slug }}.tex', u'{{ project.name }} Documentation', - u'{{ project.copyright }}', 'manual'), -]