readthedocs.org: Builds suddenly started failing a month ago with Stop Iteration error (Markdown docs)

Details

Read the Docs project URL: I’ve tried 2 different accounts thinking maybe it got corrupt. The latest one is here: https://readthedocs.org/projects/pysimplegui/
Build URL (if applicable):
Read the Docs username (if applicable): PySimpleGUI and MikeTheWatchGuy

Expected Result

I want the docs to PASS, not fail

Actual Result

I get a failure, even when using older docs. It seems to be happening due to you guys switching to Python 3.7 and that I’m using markdown instead of Sphinx

HELP! I’ve been struggling for weeks with this. I did see others with this problem and Issues claiming it’s fixed, but it’s not fixed for me. 😒

REALLY hoping someone can help. Here’s the typical error:

python /home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/bin/mkdocs build --clean --site-dir _build/html --config-file /home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/checkouts/latest/mkdocs.yml
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/checkouts/latest/_build/html 
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/lib/python3.7/site-packages/mkdocs/nav.py", line 337, in _follow
    raise StopIteration
StopIteration

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/bin/mkdocs", line 10, in <module>
    sys.exit(cli())
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/lib/python3.7/site-packages/click/core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/lib/python3.7/site-packages/click/core.py", line 717, in main
    rv = self.invoke(ctx)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/lib/python3.7/site-packages/click/core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/lib/python3.7/site-packages/click/core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/lib/python3.7/site-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/lib/python3.7/site-packages/mkdocs/__main__.py", line 156, in build_command
    ), dirty=not clean)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/lib/python3.7/site-packages/mkdocs/commands/build.py", line 282, in build
    build_pages(config, dirty=dirty)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/lib/python3.7/site-packages/mkdocs/commands/build.py", line 213, in build_pages
    site_navigation = nav.SiteNavigation(config)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/lib/python3.7/site-packages/mkdocs/nav.py", line 44, in __init__
    config, self.url_context)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pysimplegui/envs/latest/lib/python3.7/site-packages/mkdocs/nav.py", line 392, in _generate_site_navigation
    config_line, url_context, config):
RuntimeError: generator raised StopIteration

About this issue

Original URL
State: closed
Created 5 years ago
Comments: 21 (11 by maintainers)

Commits related to this issue

Revert to even earlier Python version (3.6) to avoid StopIteration error as per https://github.com/readthedocs/readthedocs.org/issues/5474 — committed to tvheadend/tvheadend-documentation by ProfYaffle a year ago

Most upvoted comments

That’s one expensive ‘tip’, but, what the heck, I signed up. You got me through several days of icky debugging of stuff I didn’t/don’t understand (ok, maybe a little better now).

You guys provide such a crucial service for me. I get comments every week, almost daily, and one of the things that’s often brought up are my docs. Users claim they chose PySimpleGUI specifically because of those docs. And without readthedocs they would be “flat”, without the Table of Contents on the left side.

Great suggestion. I’ll pay for as long as I can afford to. Hopefully it’ll be for a long time 😃

MikeTheWatchGuy on Mar 20, 2019

Dude, you’re on FIRE!

I found the “single version” setting, checked it, and POOF all of my links start working again.

You’re my hero!

MikeTheWatchGuy on Mar 18, 2019

The firs address https://pysimplegui.readthedocs.io/cookbook/ is when you set your project with this option https://docs.readthedocs.io/en/stable/single_version.html

It is used when you don’t need versioning your docs.

stsewd on Mar 18, 2019

When you use mkdocs, we don’t generate PDFs, that’s a downside of mkdocs itself https://github.com/rtfd/readthedocs.org/issues/1939.

What you are seeing is the PDF that was generated when you were using Sphinx, we are not cleaning those old PDFs when changing from sphinx to mkdocs https://github.com/rtfd/readthedocs.org/issues/4764

stsewd on Mar 18, 2019

Don’t worry, it helps us to identify where to put better docs, and also I just discovered a bug in the meantime 😃

stsewd on Mar 18, 2019

I ran the mkdocs new and it generated that yml file. I’m afraid to change anything in it because…

It’s working!!!

THANK YOU SO very much!

Man, I cannot thank you enough for your time. I know it’s tedious to step a newbie through something like this, but you spent the time with me and sure appears to have FIXED it!!

MikeTheWatchGuy on Mar 18, 2019

Looks like the only required setting for mkdocs is

site_name: Youd project name

https://www.mkdocs.org/user-guide/configuration/

stsewd on Mar 18, 2019

I saw the problem, your mkdocs.yml file isn’t valid. You should use the one that is generated by mkdocs https://www.mkdocs.org/#getting-started mkdocs new .

But, there is a bug, we are failing with a generic error instead of pointing the user the error. I’m creating a new issue about that.

Previously I LOVED readthedocs! I mean, it did everything I needed… automagically.

We still do that, we only need to update the default version of mkdocs that is installed when the users don’t have a configuration file #5332

stsewd on Mar 18, 2019

Just a few clarifications, when we don’t find a conf.py file we generate one for the user (if the project is using sphinx) or we generate a mkdocs.yml if the user is using Mkdocs.

This “magic” is removed when using a configuration file, because there was a lot of confusion.

The other problem looks like something else, I’ll take a look soon

stsewd on Mar 18, 2019

So, I saw your builds, your latest successful build was using Sphinx https://readthedocs.org/projects/pysimplegui/builds/8767815/, then it changed to build witch mkdocs.

You can read our guides to start with sphinx using markdown https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

or using markdown out of the box with mkdocs https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html

Just a few clarifications, when we don’t find a conf.py file we generate one for the user (if the project is using sphinx) or we generate a mkdocs.yml if the user is using Mkdocs.

stsewd on Mar 18, 2019