Readthedocs.org: mkdocs 0.17 is broken on CPython 3.7

[bersace]

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 !

[humitos]

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

[bersace]

Hi @humitos, thanks for the reply.

Yes, running mkdocs 0.17 and Python 3.7 locally triggers the bug.

[bersace]

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 :-)

[humitos]

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:

[bersace]

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.

[humitos]

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.

[davidfischer]

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.

[humitos]

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.

[bersace]

Thanks @stsewd ! :heart:

[stsewd]

Hope we can deploy the fix soon!

[yohanboniface]

This issue is marked as closed since a week, but it seems to me that the problem still exists, see:

https://readthedocs.org/projects/umap-project/builds/8886819/

That seems to fails with https://github.com/mkdocs/mkdocs/issues/1531

(Sorry if it's just a deployment missing.)

[stsewd]

We put this under a feature flag based on time, means that projects created before the flag was added will be using the old mkdocs by default. If you create a new project the default version will be 1.x, if you have an old project, you need to add a requirements.txt file with an updated version of mkdocs or use a configuration file to downgrade to python 3.6.

[yohanboniface]

Thanks for your answer :)

you need to add a requirements.txt file with an updated version of mkdocs

Ah, oops, it's on my -dev version:

https://github.com/umap-project/umap/blob/master/requirements-dev.txt

Thanks for the info, I've forced this file on the RTFD admin page, and it works :)