Fly-out menu broken from MkDocs projects

[marcelstoer]

This is a follow-up to #4314 (comment)

Details

• Read the Docs project URL: https://nodemcu.readthedocs.io/en/latest/en/lfs/
• Build URL (if applicable): https://readthedocs.org/projects/nodemcu/builds/7653466/

Expected Result

• The usual fly-out menu bottom left

Actual Result

• No fly-out menu, just a GitHub link and previous/next links
• If my own analysis is correct than this broke when you moved the default MkDocs version to >= 0.16 (currently 0.17.3).

Note that for https://mkdocs.readthedocs.io/en/stable/ the behavior is different for reasons unknown to me. There you get a somewhat crippled fly-out bottom-right once you scroll all the way to the end of a page.

[stsewd]

Note that for https://mkdocs.readthedocs.io/en/stable/ the behavior is different for reasons unknown to me. There you get a somewhat crippled fly-out bottom-right once you scroll all the way to the end of a page.

I guess that is because of #4448

Not sure about the problem with your docs :/

[marcelstoer]

#4448 isn't exactly the same as it mentions changes for MkDocs 1.0. The fly-out broke with your 0.15.x to 0.17.3 upgrade. It means it's currently broken for all MkDocs projects, I assume, that don't explicitly downgrade MkDocs via requirements.txt or so.

I guess this issues is missing the MkDocs label. What does the Needed: replication really mean? I can reproduce the bug.

[stsewd]

We don't have the Mkdocs label anymore, Needed replication means that someone else can replicate the issue. mkdocs is using the install option, so they are using that version to build the docs (1.0.1)

[stsewd]

Yep, I can confirm that mkdocs/mkdocs#1571

[stsewd]

I think this bug was introduced in https://github.com/rtfd/readthedocs.org/pull/4499/files, I'm investigating

[davidfischer]

Note that for https://mkdocs.readthedocs.io/en/stable/ the behavior is different for reasons unknown to me.

They are building with MkDocs 1.0+. I think the issues are related to that. I outlined some of the issues we have with MkDocs 1.0 here: #4448

[stsewd]

I found that you are using https://github.com/nodemcu/nodemcu-firmware/blob/fe40323ec49a0169ab2ca9a8722f623665b5e5ec/mkdocs.yml#L5-L6

Which I think should just work with mkdocs 0.17 :/ but the for some reason the rtd templates doesn't override the theme

[davidfischer]

I am going to move #4448 up my priority list and try to get a PR as soon as possible. There have been some significant compatibility problems between Read the Docs and mkdocs and a lot of them stem from different users using different versions of mkdocs and the difficulty in testing that. It also doesn't help that the mkdocs Read the Docs theme is outside of our control (as opposed to the Sphinx Read the Docs theme which we do control) and mkdocs made a few changes to it that broke some of what we were doing.

I think the solution is to:

• Make as few changes to mkdocs.yml as possible
• Don't pass the --theme option when executing mkdocs
• Don't override mkdocs's readthedocs theme with theme_dir or custom_dir
• Use the regular lower right corner badge-only flyout menu like we do on non-Read the Docs themes (eg. as on alabaster).

Does that sound good?

[davidfischer]

I figured out exactly what the problem is and why our template overrides weren't taking effect (which in turn broke the flyout menu). The problem is that the --theme option changed slightly with 0.17. Starting in 0.17, it seems like passing the --theme option to mkdocs (as Read the Docs currently does) causes mkdocs to ignore template overrides. Strangely, this is only true if you use the new nested theme directive for theme.custom_dir introduced in 0.17. If you use the deprecated theme_dir then template overrides take effect even with --theme.

I am going to work toward a solution along the lines of my comment above

[davidfischer]

I have a PR along the lines of what I discussed above: #4556 Any feedback on that PR is welcome.

[marcelstoer]

This being closed doesn't mean that the fix is already in production i.e. live, is it? Reason for asking: I'm still not seeing any version flyout/flyout-replacement on https://nodemcu.readthedocs.io/en/latest/en/support/.

[stsewd]

@marcelstoer yes, this isn't deployed yet. All deployed code is merged in rel branch (from master)