From 52654fc999c4c4bdf2c28931cf31e545dd5bd6ae Mon Sep 17 00:00:00 2001 From: saadmk11 Date: Thu, 18 Apr 2019 17:00:26 +0600 Subject: [PATCH 01/13] Stop creating a conf.py file automatically for users and doing magic around README handling --- readthedocs/doc_builder/backends/sphinx.py | 20 +--------- readthedocs/doc_builder/base.py | 7 ---- .../rtd_tests/tests/test_doc_builder.py | 39 +++---------------- 3 files changed, 7 insertions(+), 59 deletions(-) diff --git a/readthedocs/doc_builder/backends/sphinx.py b/readthedocs/doc_builder/backends/sphinx.py index 7a0533c17e1..24110b0e611 100644 --- a/readthedocs/doc_builder/backends/sphinx.py +++ b/readthedocs/doc_builder/backends/sphinx.py @@ -56,20 +56,6 @@ def __init__(self, *args, **kwargs): self.sphinx_build_dir, ) - def _write_config(self, master_doc='index'): - """Create ``conf.py`` if it doesn't exist.""" - 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 @@ -168,14 +154,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``. """ - if self.config_file is None: - master_doc = self.create_index(extension='rst') - self._write_config(master_doc=master_doc) - try: self.config_file = ( self.config_file or self.project.conf_file(self.version.slug) diff --git a/readthedocs/doc_builder/base.py b/readthedocs/doc_builder/base.py index 1f5712feb6a..1a9bb244d45 100644 --- a/readthedocs/doc_builder/base.py +++ b/readthedocs/doc_builder/base.py @@ -103,13 +103,6 @@ def create_index(self, extension='md', **__): 'index.{ext}'.format(ext=extension), ) if not os.path.exists(index_filename): - readme_filename = os.path.join( - docs_dir, - 'README.{ext}'.format(ext=extension), - ) - if os.path.exists(readme_filename): - return 'README' - index_file = open(index_filename, 'w+') index_text = """ diff --git a/readthedocs/rtd_tests/tests/test_doc_builder.py b/readthedocs/rtd_tests/tests/test_doc_builder.py index 49a2da4f6a4..21705e8b6a2 100644 --- a/readthedocs/rtd_tests/tests/test_doc_builder.py +++ b/readthedocs/rtd_tests/tests/test_doc_builder.py @@ -70,30 +70,23 @@ def test_conf_py_path(self, checkout_path, docs_dir): ) @patch('readthedocs.doc_builder.backends.sphinx.BaseSphinx.docs_dir') - @patch('readthedocs.doc_builder.backends.sphinx.BaseSphinx.create_index') @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( + def test_project_without_conf_py( self, checkout_path, get_conf_py_path, _, - get_config_params, create_index, docs_dir, + 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) + ``ProjectConfigurationError`` which is captured by our own code. """ tmp_dir = tempfile.mkdtemp() checkout_path.return_value = tmp_dir docs_dir.return_value = tmp_dir - create_index.return_value = 'README.rst' get_config_params.return_value = {} get_conf_py_path.side_effect = ProjectConfigurationError python_env = Virtualenv( @@ -105,36 +98,17 @@ def test_create_conf_py( build_env=self.build_env, python_env=python_env, ) - try: + with pytest.raises(ProjectConfigurationError): 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.create_index') @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_multiple_conf_py( - self, checkout_path, get_conf_py_path, _, get_config_params, - create_index, docs_dir, + self, checkout_path, get_conf_py_path, + _, get_config_params, docs_dir ): """ Test for a project with multiple ``conf.py`` files. @@ -148,7 +122,6 @@ def test_multiple_conf_py( tmp_docs_dir.join('test').mkdir().join('conf.py').write('') docs_dir.return_value = str(tmp_docs_dir) checkout_path.return_value = str(tmp_docs_dir) - create_index.return_value = 'README.rst' get_config_params.return_value = {} get_conf_py_path.side_effect = ProjectConfigurationError python_env = Virtualenv( From 24e0d80fb5d197030a059fe5ebf88c37c3d7148f Mon Sep 17 00:00:00 2001 From: saadmk11 Date: Thu, 18 Apr 2019 17:12:30 +0600 Subject: [PATCH 02/13] remove readme text --- readthedocs/doc_builder/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readthedocs/doc_builder/base.py b/readthedocs/doc_builder/base.py index 1a9bb244d45..98d4c3854ec 100644 --- a/readthedocs/doc_builder/base.py +++ b/readthedocs/doc_builder/base.py @@ -111,7 +111,7 @@ def create_index(self, extension='md', **__): This is an autogenerated index file. -Please create an ``index.{ext}`` or ``README.{ext}`` file with your own content +Please create an ``index.{ext}`` file with your own content under the root (or ``/docs``) directory in your repository. If you want to use another markup, choose a different builder in your settings. From beac3a6735cbb166a1c562f5d6ff5e8103fb8466 Mon Sep 17 00:00:00 2001 From: saadmk11 Date: Thu, 25 Apr 2019 01:17:01 +0600 Subject: [PATCH 03/13] Auto generating mkdocs.yaml removed --- readthedocs/doc_builder/backends/mkdocs.py | 4 +- readthedocs/doc_builder/backends/sphinx.py | 6 ++- readthedocs/doc_builder/exceptions.py | 4 ++ readthedocs/projects/utils.py | 20 ---------- .../rtd_tests/tests/test_doc_builder.py | 37 ++----------------- 5 files changed, 13 insertions(+), 58 deletions(-) diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py index e68d812dae9..a73cbc109f4 100644 --- a/readthedocs/doc_builder/backends/mkdocs.py +++ b/readthedocs/doc_builder/backends/mkdocs.py @@ -86,9 +86,7 @@ def load_yaml_config(self): try: return yaml.safe_load(open(self.yaml_file, 'r'),) except IOError: - return { - 'site_name': self.version.project.name, - } + raise MkDocsYAMLParseError(MkDocsYAMLParseError.NOT_FOUND) except yaml.YAMLError as exc: note = '' if hasattr(exc, 'problem_mark'): diff --git a/readthedocs/doc_builder/backends/sphinx.py b/readthedocs/doc_builder/backends/sphinx.py index 24110b0e611..994ab7f4088 100644 --- a/readthedocs/doc_builder/backends/sphinx.py +++ b/readthedocs/doc_builder/backends/sphinx.py @@ -22,7 +22,6 @@ from readthedocs.builds import utils as version_utils from readthedocs.projects.exceptions import ProjectConfigurationError from readthedocs.projects.models import Feature -from readthedocs.projects.utils import safe_write from readthedocs.restapi.client import api from ..base import BaseBuilder, restoring_chdir @@ -158,6 +157,11 @@ def append_conf(self, **__): The default content is rendered from ``doc_builder/conf.py.tmpl``. """ + if self.config_file is None: + raise ProjectConfigurationError( + ProjectConfigurationError.NOT_FOUND + ) + try: self.config_file = ( self.config_file or self.project.conf_file(self.version.slug) diff --git a/readthedocs/doc_builder/exceptions.py b/readthedocs/doc_builder/exceptions.py index eaa2858aa6e..f51ce3b8bda 100644 --- a/readthedocs/doc_builder/exceptions.py +++ b/readthedocs/doc_builder/exceptions.py @@ -71,3 +71,7 @@ class MkDocsYAMLParseError(BuildEnvironmentError): 'The "{config}" config from your MkDocs YAML config file has to be a ' 'a list of relative paths.', ) + NOT_FOUND = ugettext_noop( + 'A configuration file was not found. ' + 'Make sure you have a `mkdocs.yaml` file in your repository.', + ) diff --git a/readthedocs/projects/utils.py b/readthedocs/projects/utils.py index f83a3906a44..7c4e2862c3d 100644 --- a/readthedocs/projects/utils.py +++ b/readthedocs/projects/utils.py @@ -24,23 +24,3 @@ def version_from_slug(slug, version): else: v = Version.objects.get(project__slug=slug, slug=version) return v - - -def safe_write(filename, contents): - """ - Normalize and write to filename. - - Write ``contents`` to the given ``filename``. If the filename's - directory does not exist, it is created. Contents are written as UTF-8, - ignoring any characters that cannot be encoded as UTF-8. - - :param filename: Filename to write to - :param contents: File contents to write to file - """ - dirname = os.path.dirname(filename) - if not os.path.exists(dirname): - os.makedirs(dirname) - - with open(filename, 'w', encoding='utf-8', errors='ignore') as fh: - fh.write(contents) - fh.close() diff --git a/readthedocs/rtd_tests/tests/test_doc_builder.py b/readthedocs/rtd_tests/tests/test_doc_builder.py index 21705e8b6a2..d351afb7075 100644 --- a/readthedocs/rtd_tests/tests/test_doc_builder.py +++ b/readthedocs/rtd_tests/tests/test_doc_builder.py @@ -254,7 +254,7 @@ def test_get_theme_name_with_feature_flag(self, checkout_path, run): @patch('readthedocs.doc_builder.base.BaseBuilder.run') @patch('readthedocs.projects.models.Project.checkout_path') - def test_append_conf_create_yaml(self, checkout_path, run): + def test_append_conf_does_not_create_yaml(self, checkout_path, run): tmpdir = tempfile.mkdtemp() os.mkdir(os.path.join(tmpdir, 'docs')) checkout_path.return_value = tmpdir @@ -268,40 +268,9 @@ def test_append_conf_create_yaml(self, checkout_path, run): build_env=self.build_env, python_env=python_env, ) - self.searchbuilder.append_conf() - - run.assert_called_with('cat', 'mkdocs.yml', cwd=mock.ANY) - # There is a mkdocs.yml file created - generated_yaml = os.path.join(tmpdir, 'mkdocs.yml') - self.assertTrue(os.path.exists(generated_yaml)) - config = yaml.safe_load(open(generated_yaml)) - self.assertEqual( - config['docs_dir'], - os.path.join(tmpdir, 'docs'), - ) - self.assertEqual( - config['extra_css'], - [ - 'http://readthedocs.org/static/css/badge_only.css', - 'http://readthedocs.org/static/css/readthedocs-doc-embed.css', - ], - ) - self.assertEqual( - config['extra_javascript'], - [ - 'readthedocs-data.js', - 'http://readthedocs.org/static/core/js/readthedocs-doc-embed.js', - 'http://readthedocs.org/static/javascript/readthedocs-analytics.js', - ], - ) - self.assertIsNone( - config['google_analytics'], - ) - self.assertEqual( - config['site_name'], - 'mkdocs', - ) + with self.assertRaises(MkDocsYAMLParseError): + self.searchbuilder.append_conf() @patch('readthedocs.doc_builder.base.BaseBuilder.run') @patch('readthedocs.projects.models.Project.checkout_path') From 627091939c1c28a3b97ef7d62bdcfd9866df50e0 Mon Sep 17 00:00:00 2001 From: saadmk11 Date: Thu, 25 Apr 2019 15:20:53 +0600 Subject: [PATCH 04/13] create_index added --- readthedocs/doc_builder/backends/sphinx.py | 3 +++ readthedocs/rtd_tests/tests/test_doc_builder.py | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/readthedocs/doc_builder/backends/sphinx.py b/readthedocs/doc_builder/backends/sphinx.py index 994ab7f4088..6a0bd092bac 100644 --- a/readthedocs/doc_builder/backends/sphinx.py +++ b/readthedocs/doc_builder/backends/sphinx.py @@ -172,6 +172,9 @@ def append_conf(self, **__): ProjectConfigurationError.NOT_FOUND ) + # Create an index file if there is None. + self.create_index(extension='rst') + # Append config to project conf file tmpl = template_loader.get_template('doc_builder/conf.py.tmpl') rendered = tmpl.render(self.get_config_params()) diff --git a/readthedocs/rtd_tests/tests/test_doc_builder.py b/readthedocs/rtd_tests/tests/test_doc_builder.py index d351afb7075..b648ae483ba 100644 --- a/readthedocs/rtd_tests/tests/test_doc_builder.py +++ b/readthedocs/rtd_tests/tests/test_doc_builder.py @@ -254,7 +254,7 @@ def test_get_theme_name_with_feature_flag(self, checkout_path, run): @patch('readthedocs.doc_builder.base.BaseBuilder.run') @patch('readthedocs.projects.models.Project.checkout_path') - def test_append_conf_does_not_create_yaml(self, checkout_path, run): + def test_mkdocs_yaml_not_found(self, checkout_path, run): tmpdir = tempfile.mkdtemp() os.mkdir(os.path.join(tmpdir, 'docs')) checkout_path.return_value = tmpdir From 49e1e72f9c25022122db24e8356382f3417669df Mon Sep 17 00:00:00 2001 From: saadmk11 Date: Tue, 14 May 2019 00:21:01 +0600 Subject: [PATCH 05/13] fixed error msg --- readthedocs/doc_builder/exceptions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readthedocs/doc_builder/exceptions.py b/readthedocs/doc_builder/exceptions.py index f51ce3b8bda..8153dfe197f 100644 --- a/readthedocs/doc_builder/exceptions.py +++ b/readthedocs/doc_builder/exceptions.py @@ -73,5 +73,5 @@ class MkDocsYAMLParseError(BuildEnvironmentError): ) NOT_FOUND = ugettext_noop( 'A configuration file was not found. ' - 'Make sure you have a `mkdocs.yaml` file in your repository.', + 'Make sure you have a "mkdocs.yaml" file in your repository.', ) From 98c83100a3ac99b1ca076a50e7cce86132dd0a48 Mon Sep 17 00:00:00 2001 From: saadmk11 Date: Tue, 14 May 2019 00:36:37 +0600 Subject: [PATCH 06/13] tests updated --- readthedocs/rtd_tests/tests/test_doc_builder.py | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/readthedocs/rtd_tests/tests/test_doc_builder.py b/readthedocs/rtd_tests/tests/test_doc_builder.py index b648ae483ba..61eecfc3142 100644 --- a/readthedocs/rtd_tests/tests/test_doc_builder.py +++ b/readthedocs/rtd_tests/tests/test_doc_builder.py @@ -98,7 +98,10 @@ def test_project_without_conf_py( build_env=self.build_env, python_env=python_env, ) - with pytest.raises(ProjectConfigurationError): + with pytest.raises( + ProjectConfigurationError, + match=ProjectConfigurationError.NOT_FOUND + ): base_sphinx.append_conf() @patch('readthedocs.doc_builder.backends.sphinx.BaseSphinx.docs_dir') @@ -268,8 +271,10 @@ def test_mkdocs_yaml_not_found(self, checkout_path, run): build_env=self.build_env, python_env=python_env, ) - - with self.assertRaises(MkDocsYAMLParseError): + with pytest.raises( + MkDocsYAMLParseError, + match=MkDocsYAMLParseError.NOT_FOUND + ): self.searchbuilder.append_conf() @patch('readthedocs.doc_builder.base.BaseBuilder.run') From 61c7d440bed4521fd5446918e80ceb0449cf4253 Mon Sep 17 00:00:00 2001 From: saadmk11 Date: Tue, 14 May 2019 17:16:04 +0600 Subject: [PATCH 07/13] Updated Error msg --- readthedocs/doc_builder/exceptions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readthedocs/doc_builder/exceptions.py b/readthedocs/doc_builder/exceptions.py index 792a115b047..764e7830f5f 100644 --- a/readthedocs/doc_builder/exceptions.py +++ b/readthedocs/doc_builder/exceptions.py @@ -78,5 +78,5 @@ class MkDocsYAMLParseError(BuildEnvironmentError): ) NOT_FOUND = ugettext_noop( 'A configuration file was not found. ' - 'Make sure you have a "mkdocs.yaml" file in your repository.', + 'Make sure you have a "mkdocs.yml" file in your repository.', ) From e97ca614fa40f2b8efd9972a52fe2ace34e0eefc Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 11 Jul 2023 16:47:50 +0200 Subject: [PATCH 08/13] Lint --- readthedocs/doc_builder/backends/sphinx.py | 4 +--- readthedocs/doc_builder/exceptions.py | 2 +- readthedocs/rtd_tests/tests/test_doc_builder.py | 11 +++-------- 3 files changed, 5 insertions(+), 12 deletions(-) diff --git a/readthedocs/doc_builder/backends/sphinx.py b/readthedocs/doc_builder/backends/sphinx.py index 6ee262d0816..96bc1463067 100644 --- a/readthedocs/doc_builder/backends/sphinx.py +++ b/readthedocs/doc_builder/backends/sphinx.py @@ -254,9 +254,7 @@ def append_conf(self): The default content is rendered from ``doc_builder/conf.py.tmpl``. """ if self.config_file is None: - raise ProjectConfigurationError( - ProjectConfigurationError.NOT_FOUND - ) + raise ProjectConfigurationError(ProjectConfigurationError.NOT_FOUND) try: self.config_file = ( diff --git a/readthedocs/doc_builder/exceptions.py b/readthedocs/doc_builder/exceptions.py index 80fd781c058..1ae5a6de5e3 100644 --- a/readthedocs/doc_builder/exceptions.py +++ b/readthedocs/doc_builder/exceptions.py @@ -124,7 +124,7 @@ class MkDocsYAMLParseError(BuildUserError): "Please make sure the MkDocs YAML configuration file is not empty.", ) NOT_FOUND = gettext_noop( - 'A configuration file was not found. ' + "A configuration file was not found. " 'Make sure you have a "mkdocs.yml" file in your repository.', ) diff --git a/readthedocs/rtd_tests/tests/test_doc_builder.py b/readthedocs/rtd_tests/tests/test_doc_builder.py index 117f7e72cc6..d7b1331dc0d 100644 --- a/readthedocs/rtd_tests/tests/test_doc_builder.py +++ b/readthedocs/rtd_tests/tests/test_doc_builder.py @@ -113,8 +113,7 @@ def test_project_without_conf_py( python_env=python_env, ) with pytest.raises( - ProjectConfigurationError, - match=ProjectConfigurationError.NOT_FOUND + ProjectConfigurationError, match=ProjectConfigurationError.NOT_FOUND ): base_sphinx.append_conf() @@ -124,8 +123,7 @@ def test_project_without_conf_py( @patch('readthedocs.builds.models.Version.get_conf_py_path') @patch('readthedocs.projects.models.Project.checkout_path') def test_multiple_conf_py( - self, checkout_path, get_conf_py_path, - _, get_config_params, docs_dir + self, checkout_path, get_conf_py_path, _, get_config_params, docs_dir ): """ Test for a project with multiple ``conf.py`` files. @@ -323,10 +321,7 @@ def test_mkdocs_yaml_not_found(self, checkout_path, run): build_env=self.build_env, python_env=python_env, ) - with pytest.raises( - MkDocsYAMLParseError, - match=MkDocsYAMLParseError.NOT_FOUND - ): + with pytest.raises(MkDocsYAMLParseError, match=MkDocsYAMLParseError.NOT_FOUND): self.searchbuilder.append_conf() @patch('readthedocs.doc_builder.base.BaseBuilder.run') From 4bbbc1e0e845d823e3b450cd8de5313dd54aabad Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 11 Jul 2023 16:51:23 +0200 Subject: [PATCH 09/13] Test: remove old test --- .../rtd_tests/tests/test_doc_builder.py | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/readthedocs/rtd_tests/tests/test_doc_builder.py b/readthedocs/rtd_tests/tests/test_doc_builder.py index d7b1331dc0d..d9d8e63d928 100644 --- a/readthedocs/rtd_tests/tests/test_doc_builder.py +++ b/readthedocs/rtd_tests/tests/test_doc_builder.py @@ -305,25 +305,6 @@ def test_get_theme_name_with_feature_flag(self, checkout_path, run): Dumper=SafeDumper, ) - @patch('readthedocs.doc_builder.base.BaseBuilder.run') - @patch('readthedocs.projects.models.Project.checkout_path') - def test_mkdocs_yaml_not_found(self, checkout_path, run): - tmpdir = tempfile.mkdtemp() - os.mkdir(os.path.join(tmpdir, 'docs')) - checkout_path.return_value = tmpdir - - python_env = Virtualenv( - version=self.version, - build_env=self.build_env, - config=None, - ) - self.searchbuilder = MkdocsHTML( - build_env=self.build_env, - python_env=python_env, - ) - with pytest.raises(MkDocsYAMLParseError, match=MkDocsYAMLParseError.NOT_FOUND): - self.searchbuilder.append_conf() - @patch('readthedocs.doc_builder.base.BaseBuilder.run') @patch('readthedocs.projects.models.Project.checkout_path') def test_append_conf_existing_yaml_on_root(self, checkout_path, run): From 428f72ef70c97f6f80a233423dfd2832a4205b7b Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 11 Jul 2023 16:55:04 +0200 Subject: [PATCH 10/13] Lint --- readthedocs/rtd_tests/tests/test_doc_builder.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/readthedocs/rtd_tests/tests/test_doc_builder.py b/readthedocs/rtd_tests/tests/test_doc_builder.py index d9d8e63d928..2c6d87f36ae 100644 --- a/readthedocs/rtd_tests/tests/test_doc_builder.py +++ b/readthedocs/rtd_tests/tests/test_doc_builder.py @@ -89,8 +89,12 @@ def test_conf_py_path(self, checkout_path, docs_dir): @patch('readthedocs.builds.models.Version.get_conf_py_path') @patch('readthedocs.projects.models.Project.checkout_path') def test_project_without_conf_py( - self, checkout_path, get_conf_py_path, _, - get_config_params, docs_dir, + self, + checkout_path, + get_conf_py_path, + _, + get_config_params, + docs_dir, ): """ Test for a project without ``conf.py`` file. From 01c9f6e69285457e95793d6301cd5900cfece1a2 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 31 Jul 2023 12:33:11 +0200 Subject: [PATCH 11/13] Delete `conf.py` template --- .../templates/doc_builder/conf.py.tmpl | 218 ------------------ 1 file changed, 218 deletions(-) delete mode 100644 readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl diff --git a/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl b/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl deleted file mode 100644 index 2884c604840..00000000000 --- a/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl +++ /dev/null @@ -1,218 +0,0 @@ -{% load projects_tags %} - - -########################################################################### -# auto-created readthedocs.org specific configuration # -########################################################################### - - -# -# The following code was added during an automated build on readthedocs.org -# It is auto created and injected for every build. The result is based on the -# conf.py.tmpl file found in the readthedocs.org codebase: -# https://github.com/rtfd/readthedocs.org/blob/main/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl -# -# Note: this file shouldn't rely on extra dependencies. - -import importlib -import sys -import os.path - -# Borrowed from six. -PY3 = sys.version_info[0] == 3 -string_types = str if PY3 else basestring - -from sphinx import version_info - -# Get suffix for proper linking to GitHub -# This is deprecated in Sphinx 1.3+, -# as each page can have its own suffix -if globals().get('source_suffix', False): - if isinstance(source_suffix, string_types): - SUFFIX = source_suffix - elif isinstance(source_suffix, (list, tuple)): - # Sphinx >= 1.3 supports list/tuple to define multiple suffixes - SUFFIX = source_suffix[0] - elif isinstance(source_suffix, dict): - # Sphinx >= 1.8 supports a mapping dictionary for multiple suffixes - SUFFIX = list(source_suffix.keys())[0] # make a ``list()`` for py2/py3 compatibility - else: - # default to .rst - SUFFIX = '.rst' -else: - SUFFIX = '.rst' - -# Add RTD Static Path. Add to the end because it overwrites previous files. -if not 'html_static_path' in globals(): - html_static_path = [] -if os.path.exists('_static'): - html_static_path.append('_static') - -# Add RTD Theme only if they aren't overriding it already -using_rtd_theme = ( - ( - 'html_theme' in globals() and - html_theme in ['default'] and - # Allow people to bail with a hack of having an html_style - 'html_style' not in globals() - ) or 'html_theme' not in globals() -) -if using_rtd_theme: - html_theme = '{{ html_theme }}' - html_style = None - html_theme_options = {} - -{% comment %} -# Legacy behavior for html_theme_path: -# It is suspected that old builds with sphinx_rtd_theme required an extra -# definition of html_theme_path in order to work. -# This behavior is seen documented for old releases of sphinx_rtd_theme. -# An example of old instructions: -# https://github.com/readthedocs/sphinx_rtd_theme/blob/abd951a9cd98851269b8b5f5e59b1b4d29b1416c/README.rst -# Discussion of issue: -# https://github.com/readthedocs/readthedocs.org/pull/9654 -# -# We need to isolate the old legacy behavior because it causes Sphinx -# to skip calling the theme's setup(app) so its initialization never happens. -{% endcomment %} -# This following legacy behavior will gradually be sliced out until its deprecated and removed. -# Skipped for Sphinx 6+ -# Skipped by internal Feature flag SKIP_SPHINX_HTML_THEME_PATH -# Skipped by all new projects since SKIP_SPHINX_HTML_THEME_PATH's introduction (jan 2023) -if ( - using_rtd_theme - and version_info < (6,0) - and not {{ skip_html_theme_path|yesno:"True,False" }} - ): - theme = importlib.import_module('{{ html_theme_import }}') - if 'html_theme_path' in globals(): - html_theme_path.append(theme.get_html_theme_path()) - else: - html_theme_path = [theme.get_html_theme_path()] - -# Define websupport2_base_url and websupport2_static_url -if globals().get('websupport2_base_url', False): - websupport2_base_url = '{{ api_host }}/websupport' - websupport2_static_url = '{{ settings.STATIC_URL }}' - - -#Add project information to the template context. -context = { - 'using_theme': using_rtd_theme, - 'html_theme': html_theme, - 'current_version': "{{ version.verbose_name }}", - 'version_slug': "{{ version.slug }}", - 'MEDIA_URL': "{{ settings.MEDIA_URL }}", - 'STATIC_URL': "{{ settings.STATIC_URL }}", - 'PRODUCTION_DOMAIN': "{{ settings.PRODUCTION_DOMAIN }}", - 'proxied_static_path': "{{ proxied_static_path }}", - 'versions': [{% for version in versions %} - ("{{ version.slug }}", "/{{ version.project.language }}/{{ version.slug}}/"),{% endfor %} - ], - 'downloads': [ {% for key, val in downloads.items %} - ("{{ key }}", "{{ val }}"),{% endfor %} - ], - 'subprojects': [ {% for slug, url in subproject_urls %} - ("{{ slug }}", "{{ url }}"),{% endfor %} - ], - 'slug': '{{ project.slug }}', - 'name': u'{{ project.name }}', - 'rtd_language': u'{{ project.language }}', - 'programming_language': u'{{ project.programming_language }}', - 'canonical_url': '{{ project.get_canonical_url }}', - 'analytics_code': '{{ project.analytics_code }}', - 'single_version': {{ project.single_version }}, - 'conf_py_path': '{{ conf_py_path }}', - 'api_host': '{{ api_host }}', - 'github_user': '{{ github_user }}', - 'proxied_api_host': '{{ project.proxied_api_host }}', - 'github_repo': '{{ github_repo }}', - 'github_version': '{{ github_version }}', - 'display_github': {{ display_github }}, - 'bitbucket_user': '{{ bitbucket_user }}', - 'bitbucket_repo': '{{ bitbucket_repo }}', - 'bitbucket_version': '{{ bitbucket_version }}', - 'display_bitbucket': {{ display_bitbucket }}, - 'gitlab_user': '{{ gitlab_user }}', - 'gitlab_repo': '{{ gitlab_repo }}', - 'gitlab_version': '{{ gitlab_version }}', - 'display_gitlab': {{ display_gitlab }}, - 'READTHEDOCS': True, - 'using_theme': (html_theme == "default"), - 'new_theme': (html_theme == "sphinx_rtd_theme"), - 'source_suffix': SUFFIX, - 'ad_free': {% if project.show_advertising %}False{% else %}True{% endif %}, - 'docsearch_disabled': {{ docsearch_disabled }}, - 'user_analytics_code': '{{ project.analytics_code|default_if_none:'' }}', - 'global_analytics_code': {% if project.analytics_disabled %}None{% else %}'{{ settings.GLOBAL_ANALYTICS_CODE }}'{% endif %}, - 'commit': {% if project.repo_type == 'git' %}'{{ commit|slice:"8" }}'{% else %}'{{ commit }}'{% endif %}, -} - -# For sphinx >=1.8 we can use html_baseurl to set the canonical URL. -# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl -if version_info >= (1, 8): - if not globals().get('html_baseurl'): - html_baseurl = context['canonical_url'] - context['canonical_url'] = None - - -{# Provide block for extending context data from child template #} -{% block extra_context %}{% endblock %} - -if 'html_context' in globals(): - for key in context: - if key not in html_context: - html_context[key] = context[key] -else: - html_context = context - -# Add custom RTD extension -if 'extensions' in globals(): - # Insert at the beginning because it can interfere - # with other extensions. - # See https://github.com/rtfd/readthedocs.org/pull/4054 - extensions.insert(0, "readthedocs_ext.readthedocs") -else: - extensions = ["readthedocs_ext.readthedocs"] - -# Add External version warning banner to the external version documentation -if '{{ version.type }}' == 'external': - extensions.insert(1, "readthedocs_ext.external_version_warning") - readthedocs_vcs_url = '{{ vcs_url }}' - readthedocs_build_url = '{{ build_url }}' - -project_language = '{{ project.language }}' - -# User's Sphinx configurations -language_user = globals().get('language', None) -latex_engine_user = globals().get('latex_engine', None) -latex_elements_user = globals().get('latex_elements', None) - -# Remove this once xindy gets installed in Docker image and XINDYOPS -# env variable is supported -# https://github.com/rtfd/readthedocs-docker-images/pull/98 -latex_use_xindy = False - -chinese = any([ - language_user in ('zh_CN', 'zh_TW'), - project_language in ('zh_CN', 'zh_TW'), -]) - -japanese = any([ - language_user == 'ja', - project_language == 'ja', -]) - -if chinese: - latex_engine = latex_engine_user or 'xelatex' - - latex_elements_rtd = { - 'preamble': '\\usepackage[UTF8]{ctex}\n', - } - latex_elements = latex_elements_user or latex_elements_rtd -elif japanese: - latex_engine = latex_engine_user or 'platex' - -# Make sure our build directory is always excluded -exclude_patterns = globals().get('exclude_patterns', []) -exclude_patterns.extend(['_build']) From eef1165b69b84efcf4587a6996c338fd289d2396 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 16 Aug 2023 13:34:20 +0200 Subject: [PATCH 12/13] Build: fail the build if `docs/conf.py` doesn't exist --- readthedocs/doc_builder/backends/sphinx.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/readthedocs/doc_builder/backends/sphinx.py b/readthedocs/doc_builder/backends/sphinx.py index 96bc1463067..33eb91f29dc 100644 --- a/readthedocs/doc_builder/backends/sphinx.py +++ b/readthedocs/doc_builder/backends/sphinx.py @@ -256,22 +256,22 @@ def append_conf(self): if self.config_file is None: raise ProjectConfigurationError(ProjectConfigurationError.NOT_FOUND) + self.config_file = self.config_file or self.project.conf_file(self.version.slug) + try: - self.config_file = ( - self.config_file or self.project.conf_file(self.version.slug) - ) + if not os.path.exists(self.config_file): + raise UserFileNotFound + # Allow symlinks, but only the ones that resolve inside the base directory. outfile = safe_open( self.config_file, "a", allow_symlinks=True, base_path=self.project_path ) if not outfile: - raise UserFileNotFound( - UserFileNotFound.FILE_NOT_FOUND.format(self.config_file) - ) - except IOError as exc: - raise ProjectConfigurationError( - ProjectConfigurationError.NOT_FOUND - ) from exc + raise UserFileNotFound + except UserFileNotFound: + raise UserFileNotFound( + UserFileNotFound.FILE_NOT_FOUND.format(self.config_file) + ) # Append config to project conf file tmpl = template_loader.get_template('doc_builder/conf.py.tmpl') From 96621fda22e26e99db27f98cb4a65db3badb5d00 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 17 Aug 2023 15:55:00 +0200 Subject: [PATCH 13/13] Build: raise exception if no config file --- readthedocs/doc_builder/backends/sphinx.py | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/readthedocs/doc_builder/backends/sphinx.py b/readthedocs/doc_builder/backends/sphinx.py index 33eb91f29dc..9f9bdf48864 100644 --- a/readthedocs/doc_builder/backends/sphinx.py +++ b/readthedocs/doc_builder/backends/sphinx.py @@ -258,21 +258,18 @@ def append_conf(self): self.config_file = self.config_file or self.project.conf_file(self.version.slug) - try: - if not os.path.exists(self.config_file): - raise UserFileNotFound - - # Allow symlinks, but only the ones that resolve inside the base directory. - outfile = safe_open( - self.config_file, "a", allow_symlinks=True, base_path=self.project_path - ) - if not outfile: - raise UserFileNotFound - except UserFileNotFound: + if not os.path.exists(self.config_file): raise UserFileNotFound( UserFileNotFound.FILE_NOT_FOUND.format(self.config_file) ) + # 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())