Merge pull request #4556 from rtfd/davidfischer/mkdocs-upgrade-again

Updates and simplification for mkdocs

Author: davidfischer

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 {

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']);

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 () {

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;

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

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)

readthedocs/rtd_tests/tests/test_doc_builder.py

@@ -150,6 +150,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):
@@ -258,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):