From a30768d01801ebddbb379e8626aadd5125cd7928 Mon Sep 17 00:00:00 2001 From: David Fischer Date: Wed, 22 Aug 2018 09:51:40 -0700 Subject: [PATCH 1/2] Updates and simplification for mkdocs --- media/css/readthedocs-doc-embed.css | 3 + .../static-src/core/js/doc-embed/footer.js | 3 +- .../static-src/core/js/doc-embed/rtd-data.js | 3 +- .../static-src/core/js/doc-embed/sphinx.js | 2 +- readthedocs/doc_builder/backends/mkdocs.py | 45 +-------- .../rtd_tests/tests/test_doc_builder.py | 98 +++++++------------ .../mkdocs/readthedocs/searchbox.html | 5 - .../mkdocs/readthedocs/versions.html | 8 -- 8 files changed, 46 insertions(+), 121 deletions(-) delete mode 100644 readthedocs/templates/mkdocs/readthedocs/searchbox.html delete mode 100644 readthedocs/templates/mkdocs/readthedocs/versions.html diff --git a/media/css/readthedocs-doc-embed.css b/media/css/readthedocs-doc-embed.css index 8488690cfc8..f653789e265 100644 --- a/media/css/readthedocs-doc-embed.css +++ b/media/css/readthedocs-doc-embed.css @@ -7,6 +7,9 @@ display: block; bottom: 50px; + + /* Workaround for mkdocs which set a specific height for this element */ + height: auto; } .rst-other-versions { diff --git a/readthedocs/core/static-src/core/js/doc-embed/footer.js b/readthedocs/core/static-src/core/js/doc-embed/footer.js index a8eed6d70b4..5fabfb5c4e5 100644 --- a/readthedocs/core/static-src/core/js/doc-embed/footer.js +++ b/readthedocs/core/static-src/core/js/doc-embed/footer.js @@ -7,7 +7,8 @@ function injectFooter(data) { // If the theme looks like ours, update the existing badge // otherwise throw a a full one into the page. - if (config.is_rtd_like_theme()) { + // Do not inject for mkdocs even for the RTD theme + if (config.is_sphinx_builder() && config.is_rtd_like_theme()) { $("div.rst-other-versions").html(data['html']); } else { $("body").append(data['html']); diff --git a/readthedocs/core/static-src/core/js/doc-embed/rtd-data.js b/readthedocs/core/static-src/core/js/doc-embed/rtd-data.js index 4a93d441887..cbe4d173f4e 100644 --- a/readthedocs/core/static-src/core/js/doc-embed/rtd-data.js +++ b/readthedocs/core/static-src/core/js/doc-embed/rtd-data.js @@ -8,6 +8,7 @@ var constants = require('./constants'); var configMethods = { is_rtd_like_theme: function () { + // Returns true for the Read the Docs theme on both sphinx and mkdocs if ($('div.rst-other-versions').length === 1) { // Crappy heuristic, but people change the theme name // So we have to do some duck typing. @@ -30,7 +31,7 @@ var configMethods = { }, is_mkdocs_builder: function () { - return (!('builder' in this) || this.builder === 'mkdocs'); + return ('builder' in this && this.builder === 'mkdocs'); }, get_theme_name: function () { diff --git a/readthedocs/core/static-src/core/js/doc-embed/sphinx.js b/readthedocs/core/static-src/core/js/doc-embed/sphinx.js index 48d0fa74733..fe6de3f0e09 100644 --- a/readthedocs/core/static-src/core/js/doc-embed/sphinx.js +++ b/readthedocs/core/static-src/core/js/doc-embed/sphinx.js @@ -29,7 +29,7 @@ function init() { /// Inject the Read the Docs Sphinx theme code /// This is necessary on older versions of the RTD theme (<0.4.0) /// and on themes other then the RTD theme (used for the version menu) - if ((rtd.builder === undefined || rtd.builder === 'sphinx') && window.SphinxRtdTheme === undefined) { + if (window.SphinxRtdTheme === undefined) { sphinx_theme = require('sphinx-rtd-theme'); // eslint-disable-line global-require var theme = sphinx_theme.ThemeNav; diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py index 86845882e81..2da0b9ee8d1 100644 --- a/readthedocs/doc_builder/backends/mkdocs.py +++ b/readthedocs/doc_builder/backends/mkdocs.py @@ -39,17 +39,8 @@ class BaseMkdocs(BaseBuilder): """Mkdocs builder.""" - use_theme = True - - # The default theme for mkdocs (outside of RTD) is the 'mkdocs' theme - # For RTD, our default is the 'readthedocs' theme - READTHEDOCS_THEME_NAME = 'readthedocs' - - # Overrides for the 'readthedocs' theme that include - # search utilities and version selector - READTHEDOCS_TEMPLATE_OVERRIDE_DIR = ( - '%s/readthedocs/templates/mkdocs/readthedocs' % settings.SITE_ROOT - ) + # The default theme for mkdocs is the 'mkdocs' theme + DEFAULT_THEME_NAME = 'mkdocs' def __init__(self, *args, **kwargs): super(BaseMkdocs, self).__init__(*args, **kwargs) @@ -133,11 +124,6 @@ def append_conf(self, **__): # This supports using RTD's privacy improvements around analytics user_config['google_analytics'] = None - # If using the readthedocs theme, apply the readthedocs.org overrides - # These use a global readthedocs search - # and customize the version selector. - self.apply_theme_override(user_config) - # Write the modified mkdocs configuration yaml.safe_dump( user_config, @@ -198,8 +184,6 @@ def build(self): '--site-dir', self.build_dir, '--config-file', self.yaml_file, ] - if self.use_theme: - build_command.extend(['--theme', 'readthedocs']) cmd_ret = self.run( *build_command, cwd=checkout_path, @@ -220,7 +204,7 @@ def get_theme_name(self, mkdocs_config): theme_setting = mkdocs_config.get('theme') if isinstance(theme_setting, dict): # Full nested theme config (the new configuration) - return theme_setting.get('name') or self.READTHEDOCS_THEME_NAME + return theme_setting.get('name') or self.DEFAULT_THEME_NAME if theme_setting: # A string which is the name of the theme @@ -231,27 +215,7 @@ def get_theme_name(self, mkdocs_config): # Use the name of the directory in this project's custom theme directory return theme_dir.rstrip('/').split('/')[-1] - return self.READTHEDOCS_THEME_NAME - - def apply_theme_override(self, mkdocs_config): - """ - Apply theme overrides for the RTD theme (modifies the ``mkdocs_config`` parameter) - - In v0.17.0, the theme configuration switched - from two separate configs (both optional) to a nested directive. - How to override the theme depends on whether the new or old configuration - is used. - - :see: http://www.mkdocs.org/about/release-notes/#theme-customization-1164 - """ - if self.get_theme_name(mkdocs_config) == self.READTHEDOCS_THEME_NAME: - # Overriding the theme is only necessary - # if the 'readthedocs' theme is used. - theme_setting = mkdocs_config.get('theme') - if isinstance(theme_setting, dict): - theme_setting['custom_dir'] = self.READTHEDOCS_TEMPLATE_OVERRIDE_DIR - else: - mkdocs_config['theme_dir'] = self.READTHEDOCS_TEMPLATE_OVERRIDE_DIR + return self.DEFAULT_THEME_NAME class MkdocsHTML(BaseMkdocs): @@ -264,4 +228,3 @@ class MkdocsJSON(BaseMkdocs): type = 'mkdocs_json' builder = 'json' build_dir = '_build/json' - use_theme = False diff --git a/readthedocs/rtd_tests/tests/test_doc_builder.py b/readthedocs/rtd_tests/tests/test_doc_builder.py index c2b4e95ec51..cf16d549d72 100644 --- a/readthedocs/rtd_tests/tests/test_doc_builder.py +++ b/readthedocs/rtd_tests/tests/test_doc_builder.py @@ -127,6 +127,40 @@ def setUp(self): self.build_env.project = self.project self.build_env.version = self.version + def test_get_theme_name(self): + builder = MkdocsHTML( + build_env=self.build_env, + python_env=None + ) + + # The default theme is mkdocs but in mkdocs>=1.0, theme is required + self.assertEqual(builder.get_theme_name({}), 'mkdocs') + + # mkdocs<0.17 syntax + config = { + 'theme': 'readthedocs', + } + self.assertEqual(builder.get_theme_name(config), 'readthedocs') + + # mkdocs>=0.17 syntax + config = { + 'theme': { + 'name': 'test_theme', + }, + } + self.assertEqual(builder.get_theme_name(config), 'test_theme') + + # No theme but just a directory + config = { + 'theme_dir': '/path/to/mydir', + } + self.assertEqual(builder.get_theme_name(config), 'mydir') + config = { + 'theme_dir': '/path/to/mydir/', + } + self.assertEqual(builder.get_theme_name(config), 'mydir') + + @patch('readthedocs.doc_builder.base.BaseBuilder.run') @patch('readthedocs.projects.models.Project.checkout_path') def test_append_conf_create_yaml(self, checkout_path, run): @@ -225,70 +259,6 @@ def test_append_conf_existing_yaml_on_root(self, checkout_path, run): 'mkdocs' ) - @patch('readthedocs.doc_builder.base.BaseBuilder.run') - @patch('readthedocs.projects.models.Project.checkout_path') - def test_override_theme_new_style(self, checkout_path, run): - tmpdir = tempfile.mkdtemp() - os.mkdir(os.path.join(tmpdir, 'docs')) - yaml_file = os.path.join(tmpdir, 'mkdocs.yml') - yaml.safe_dump( - { - 'theme': { - 'name': 'readthedocs', - }, - 'site_name': 'mkdocs', - 'docs_dir': 'docs', - }, - open(yaml_file, 'w') - ) - checkout_path.return_value = tmpdir - - self.searchbuilder = MkdocsHTML( - build_env=self.build_env, - python_env=None - ) - self.searchbuilder.append_conf() - - run.assert_called_with('cat', 'mkdocs.yml', cwd=mock.ANY) - - config = yaml.safe_load(open(yaml_file)) - self.assertEqual( - config['theme'], - { - 'name': 'readthedocs', - 'custom_dir': BaseMkdocs.READTHEDOCS_TEMPLATE_OVERRIDE_DIR - } - ) - - @patch('readthedocs.doc_builder.base.BaseBuilder.run') - @patch('readthedocs.projects.models.Project.checkout_path') - def test_override_theme_old_style(self, checkout_path, run): - tmpdir = tempfile.mkdtemp() - os.mkdir(os.path.join(tmpdir, 'docs')) - yaml_file = os.path.join(tmpdir, 'mkdocs.yml') - yaml.safe_dump( - { - 'theme': 'readthedocs', - 'site_name': 'mkdocs', - 'docs_dir': 'docs', - }, - open(yaml_file, 'w') - ) - checkout_path.return_value = tmpdir - - self.searchbuilder = MkdocsHTML( - build_env=self.build_env, - python_env=None - ) - self.searchbuilder.append_conf() - - run.assert_called_with('cat', 'mkdocs.yml', cwd=mock.ANY) - - config = yaml.safe_load(open(yaml_file)) - self.assertEqual( - config['theme_dir'], - BaseMkdocs.READTHEDOCS_TEMPLATE_OVERRIDE_DIR - ) @patch('readthedocs.doc_builder.base.BaseBuilder.run') @patch('readthedocs.projects.models.Project.checkout_path') diff --git a/readthedocs/templates/mkdocs/readthedocs/searchbox.html b/readthedocs/templates/mkdocs/readthedocs/searchbox.html deleted file mode 100644 index b89edd200dc..00000000000 --- a/readthedocs/templates/mkdocs/readthedocs/searchbox.html +++ /dev/null @@ -1,5 +0,0 @@ -
-
- -
-
\ No newline at end of file diff --git a/readthedocs/templates/mkdocs/readthedocs/versions.html b/readthedocs/templates/mkdocs/readthedocs/versions.html deleted file mode 100644 index 1cec667e914..00000000000 --- a/readthedocs/templates/mkdocs/readthedocs/versions.html +++ /dev/null @@ -1,8 +0,0 @@ -
- - Read the Docs - - -
-
-
From 171ce95cc5573b8269f8845240ef442dfe315b47 Mon Sep 17 00:00:00 2001 From: David Fischer Date: Wed, 12 Sep 2018 15:16:33 -0700 Subject: [PATCH 2/2] Fix a merge mistake --- readthedocs/doc_builder/base.py | 2 +- .../rtd_tests/tests/test_doc_builder.py | 75 ------------------- 2 files changed, 1 insertion(+), 76 deletions(-) diff --git a/readthedocs/doc_builder/base.py b/readthedocs/doc_builder/base.py index df9882c56f0..83aac0da617 100644 --- a/readthedocs/doc_builder/base.py +++ b/readthedocs/doc_builder/base.py @@ -46,7 +46,7 @@ def __init__(self, build_env, python_env, force=False): self.python_env = python_env self.version = build_env.version self.project = build_env.project - self.config = python_env.config + self.config = python_env.config if python_env else None self._force = force self.target = self.project.artifact_path( version=self.version.slug, type_=self.type) diff --git a/readthedocs/rtd_tests/tests/test_doc_builder.py b/readthedocs/rtd_tests/tests/test_doc_builder.py index 3de7192b4a7..b07668f1084 100644 --- a/readthedocs/rtd_tests/tests/test_doc_builder.py +++ b/readthedocs/rtd_tests/tests/test_doc_builder.py @@ -292,81 +292,6 @@ def test_append_conf_existing_yaml_on_root(self, checkout_path, run): 'mkdocs' ) - @patch('readthedocs.doc_builder.base.BaseBuilder.run') - @patch('readthedocs.projects.models.Project.checkout_path') - def test_override_theme_new_style(self, checkout_path, run): - tmpdir = tempfile.mkdtemp() - os.mkdir(os.path.join(tmpdir, 'docs')) - yaml_file = os.path.join(tmpdir, 'mkdocs.yml') - yaml.safe_dump( - { - 'theme': { - 'name': 'readthedocs', - }, - 'site_name': 'mkdocs', - 'docs_dir': 'docs', - }, - open(yaml_file, 'w') - ) - 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, - ) - self.searchbuilder.append_conf() - - run.assert_called_with('cat', 'mkdocs.yml', cwd=mock.ANY) - - config = yaml.safe_load(open(yaml_file)) - self.assertEqual( - config['theme'], - { - 'name': 'readthedocs', - 'custom_dir': BaseMkdocs.READTHEDOCS_TEMPLATE_OVERRIDE_DIR - } - ) - - @patch('readthedocs.doc_builder.base.BaseBuilder.run') - @patch('readthedocs.projects.models.Project.checkout_path') - def test_override_theme_old_style(self, checkout_path, run): - tmpdir = tempfile.mkdtemp() - os.mkdir(os.path.join(tmpdir, 'docs')) - yaml_file = os.path.join(tmpdir, 'mkdocs.yml') - yaml.safe_dump( - { - 'theme': 'readthedocs', - 'site_name': 'mkdocs', - 'docs_dir': 'docs', - }, - open(yaml_file, 'w') - ) - 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, - ) - self.searchbuilder.append_conf() - - run.assert_called_with('cat', 'mkdocs.yml', cwd=mock.ANY) - - config = yaml.safe_load(open(yaml_file)) - self.assertEqual( - config['theme_dir'], - BaseMkdocs.READTHEDOCS_TEMPLATE_OVERRIDE_DIR - ) - @patch('readthedocs.doc_builder.base.BaseBuilder.run') @patch('readthedocs.projects.models.Project.checkout_path') def test_dont_override_theme(self, checkout_path, run):