diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py index de7037dc47d..2a790e27364 100644 --- a/readthedocs/doc_builder/backends/mkdocs.py +++ b/readthedocs/doc_builder/backends/mkdocs.py @@ -17,9 +17,6 @@ log = logging.getLogger(__name__) -TEMPLATE_DIR = '%s/readthedocs/templates/mkdocs/readthedocs' % settings.SITE_ROOT -OVERRIDE_TEMPLATE_DIR = '%s/readthedocs/templates/mkdocs/overrides' % settings.SITE_ROOT - def get_absolute_media_url(): """ @@ -42,6 +39,16 @@ class BaseMkdocs(BaseBuilder): 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 + ) + def __init__(self, *args, **kwargs): super(BaseMkdocs, self).__init__(*args, **kwargs) self.old_artifact_path = os.path.join( @@ -96,10 +103,6 @@ def append_conf(self, **__): '%scss/readthedocs-doc-embed.css' % media_url, ]) - # Set our custom theme dir for mkdocs - if 'theme_dir' not in user_config and self.use_theme: - user_config['theme_dir'] = TEMPLATE_DIR - docs_path = os.path.join(self.root_path, docs_dir) # RTD javascript writing @@ -111,20 +114,25 @@ def append_conf(self, **__): # This supports using RTD's privacy improvements around analytics user_config['google_analytics'] = None - # Write the mkdocs configuration + # 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, open(os.path.join(self.root_path, 'mkdocs.yml'), 'w') ) + # Write the mkdocs.yml to the build logs + self.run( + 'cat', + 'mkdocs.yml', + cwd=self.root_path, + ) + def generate_rtd_data(self, docs_dir, mkdocs_config): """Generate template properties and render readthedocs-data.js.""" - # Get the theme name - theme_name = 'readthedocs' - theme_dir = mkdocs_config.get('theme_dir') - if theme_dir: - theme_name = theme_dir.rstrip('/').split('/')[-1] - # Use the analytics code from mkdocs.yml if it isn't set already by Read the Docs analytics_code = self.version.project.analytics_code if not analytics_code and mkdocs_config.get('google_analytics'): @@ -138,7 +146,7 @@ def generate_rtd_data(self, docs_dir, mkdocs_config): 'language': self.version.project.language, 'programming_language': self.version.project.programming_language, 'page': None, - 'theme': theme_name, + 'theme': self.get_theme_name(mkdocs_config), 'builder': "mkdocs", 'docroot': docs_dir, 'source_suffix': ".md", @@ -176,6 +184,51 @@ def build(self): ) return cmd_ret.successful + def get_theme_name(self, mkdocs_config): + """ + Get the theme configuration in the mkdocs_config + + In v0.17.0, the theme configuration switched + from two separate configs (both optional) to a nested directive. + + :see: http://www.mkdocs.org/about/release-notes/#theme-customization-1164 + :returns: the name of the theme RTD will use + """ + 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 + + if theme_setting: + # A string which is the name of the theme + return theme_setting + + theme_dir = mkdocs_config.get('theme_dir') + if theme_dir: + # 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 + class MkdocsHTML(BaseMkdocs): type = 'mkdocs' @@ -188,15 +241,3 @@ class MkdocsJSON(BaseMkdocs): builder = 'json' build_dir = '_build/json' use_theme = False - - def build(self): - user_config = yaml.safe_load( - open(os.path.join(self.root_path, 'mkdocs.yml'), 'r') - ) - if user_config['theme_dir'] == TEMPLATE_DIR: - del user_config['theme_dir'] - yaml.safe_dump( - user_config, - open(os.path.join(self.root_path, 'mkdocs.yml'), 'w') - ) - return super(MkdocsJSON, self).build() diff --git a/readthedocs/doc_builder/python_environments.py b/readthedocs/doc_builder/python_environments.py index 2d16ff3fbe3..8b54278956f 100644 --- a/readthedocs/doc_builder/python_environments.py +++ b/readthedocs/doc_builder/python_environments.py @@ -235,7 +235,7 @@ def install_core_requirements(self): ] if self.project.documentation_type == 'mkdocs': - requirements.append('mkdocs==0.15.0') + requirements.append('mkdocs==0.17.3') else: # We will assume semver here and only automate up to the next # backward incompatible release: 2.x diff --git a/readthedocs/rtd_tests/tests/test_doc_building.py b/readthedocs/rtd_tests/tests/test_doc_building.py index 4b678ce085f..de5c7b92f5f 100644 --- a/readthedocs/rtd_tests/tests/test_doc_building.py +++ b/readthedocs/rtd_tests/tests/test_doc_building.py @@ -1171,7 +1171,7 @@ def test_install_core_requirements_mkdocs(self): requirements_mkdocs = [ 'commonmark==0.5.4', 'recommonmark==0.4.0', - 'mkdocs==0.15.0', + 'mkdocs==0.17.3', ] requirements = self.base_requirements + requirements_mkdocs args = self.pip_install_args + requirements diff --git a/requirements/pip.txt b/requirements/pip.txt index 026c570d97c..1cd9382144b 100644 --- a/requirements/pip.txt +++ b/requirements/pip.txt @@ -11,9 +11,7 @@ sphinx_rtd_theme==0.2.5b1 Pygments==2.2.0 -# latest compatible version with our code -# https://github.com/rtfd/readthedocs.org/pull/2916#discussion_r172991757 -mkdocs==0.15.0 +mkdocs==0.17.3 django==1.9.13 six==1.11.0