Repository: readthedocs/readthedocs.org

Issue:
mkdocs 0.17 is broken on CPython 3.7
Hi,

## Details

* Read the Docs project URL: https://ldap2pg.readthedocs.io/en/latest/
* Build URL (if applicable): https://readthedocs.org/projects/ldap2pg/builds/8609860/
* Read the Docs username (if applicable): bersace

## Expected Result

- Choose mkdocs
- Choose CPython-3.x runtime
- trigger build
- docs is properly built

## Actual Result

Build fails with a cryptic `RuntimeError: generator raised StopIteration` due to incompatibility between mkdocs 0.17 with CPython 3.7

This is a show stopper for Python3-only projects, needed to install projects along mkdocs. For 2019, switching back to 2.7 may work around the problem.

Thanks for RTD. It's great !


Discussion:
Are you able to build the docs locally? At first sight, this doesn't seem to be a problem with Read the Docs itself but an incompatibility between mkdocs and Py3.7.

You can use a YAML file and define Python 3.6 in case that 3.7 is the problem.

> Thanks for RTD. It's great !

Thanks for using it ;)
Hi @humitos, thanks for the reply.

Yes, running mkdocs 0.17 and Python 3.7 locally triggers the bug.
> You can use a YAML file and define Python 3.6 in case that 3.7 is the problem.

Good to know there is a better workaround than 2.7 :-)
Please, use YAMLv2: https://docs.readthedocs.io/en/latest/config-file/v2.html

I'm closing this issue here, but feel free to reopen if you consider.

> Good to know there is a better workaround than 2.7 :-)

:100: 
Well, there is multiple workarounds (for ldap2pg, I bin mkdocs in a requirements.txt file), but that would be better if rtd wont fail when you pick mkdocs + cpython3 in configuration. Thats going to be a fair default configuration for many projects now that 2.7 is going EOL.
> but that would be better if rtd wont fail when you pick mkdocs + cpython3 in configuration. Thats going to be a fair default configuration for many projects now that 2.7 is going EOL.

You are right! We should consider to default to `1.0.4` instead. @davidfischer were you playing with new mkdocs version? do you think we are close to upgrade our default? We could use a feature flag to default to `1.0.4` for new projects and keep `0.17` for old ones.
> You are right! We should consider to default to `1.0.4` instead. @davidfischer were you playing with new mkdocs version? do you think we are close to upgrade our default? We could use a feature flag to default to `1.0.4` for new projects and keep `0.17` for old ones.

We probably have to do the latter. Mkdoc 1.x and 0.17.x are mostly compatible but there are some configuration file changes that can cause build errors. In general, it should be smooth to just use Mkdocs 1.x for new projects.

I strongly suggest that users of mkdocs (and Sphinx for that matter) pin to the major version in their requirements file as @bersace has done. This will make sure that their docs continue to build when Read the Docs changes the default version.
> In general, it should be smooth to just use Mkdocs 1.x for new projects.

This is the way to go, then.

I'm removing design decision from this issue and marking as accepted so we do this.

Resolving patch:
diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -1,10 +1,9 @@
-# -*- coding: utf-8 -*-
-
 """
 MkDocs_ backend for building docs.
 
 .. _MkDocs: http://www.mkdocs.org/
 """
+
 import json
 import logging
 import os
diff --git a/readthedocs/doc_builder/python_environments.py b/readthedocs/doc_builder/python_environments.py
--- a/readthedocs/doc_builder/python_environments.py
+++ b/readthedocs/doc_builder/python_environments.py
@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """An abstraction over virtualenv and Conda environments."""
 
 import copy
@@ -9,8 +7,6 @@
 import os
 import shutil
 
-from django.conf import settings
-
 from readthedocs.config import PIP, SETUPTOOLS
 from readthedocs.config.models import PythonInstall, PythonInstallRequirements
 from readthedocs.doc_builder.config import load_yaml_config
@@ -295,7 +291,13 @@ def install_core_requirements(self):
         ]
 
         if self.config.doctype == 'mkdocs':
-            requirements.append('mkdocs==0.17.3')
+            requirements.append(
+                self.project.get_feature_value(
+                    Feature.DEFAULT_TO_MKDOCS_0_17_3,
+                    positive='mkdocs==0.17.3',
+                    negative='mkdocs<1.1',
+                ),
+            )
         else:
             # We will assume semver here and only automate up to the next
             # backward incompatible release: 2.x
diff --git a/readthedocs/projects/models.py b/readthedocs/projects/models.py
--- a/readthedocs/projects/models.py
+++ b/readthedocs/projects/models.py
@@ -1312,6 +1312,7 @@ def add_features(sender, **kwargs):
     USE_TESTING_BUILD_IMAGE = 'use_testing_build_image'
     SHARE_SPHINX_DOCTREE = 'share_sphinx_doctree'
     USE_PDF_LATEXMK = 'use_pdf_latexmk'
+    DEFAULT_TO_MKDOCS_0_17_3 = 'default_to_mkdocs_0_17_3'
 
     FEATURES = (
         (USE_SPHINX_LATEST, _('Use latest version of Sphinx')),
@@ -1346,6 +1347,10 @@ def add_features(sender, **kwargs):
             SHARE_SPHINX_DOCTREE,
             _('Use shared directory for doctrees'),
         ),
+        (
+            DEFAULT_TO_MKDOCS_0_17_3,
+            _('Install mkdocs 0.17.3 by default')
+        ),
     )
 
     projects = models.ManyToManyField(


Test patch: