Setting up latest mkdocs in RTD configuration does not result with the actual latest mkdocs version.

[GraionDilach]

Details

OpenRA/OpenRA#18681 is a WIP update in the @OpenRA project documentation. During the PR review, it was noticed that the generated document featured mkdocs/mkdocs#2027. This bug is fixed in mkdocs version 1.1.1 - mkdocs/mkdocs@63b3eb5 - already but RTD does not deploy the bugfix.

I don't know Python but I suspect
https://github.com/readthedocs/readthedocs.org/blob/master/readthedocs/doc_builder/python_environments.py#L373 caps the version to 1.1 which became outdated by now (blame claims it's a two year old line) and prevents RTD to deploy versions above 1.1.

Expected Result

Setting mkdocs to use the latest release deploys on mkdocs's latest release.

Actual Result

Setting mkdocs to use the latest release deploys on mkdocs version 1.1 instead of 1.1.2.

[GraionDilach]

Pinging @pchote and @Mailaender for interest.

[stsewd]

You can install any version of mkdocs you want, see https://docs.readthedocs.io/en/stable/guides/specifying-dependencies.html

[GraionDilach]

Yes, I understand this part. Manually pinning the latest version shouldn't be the solution to circumvent an outdated default value though.

The feature flag added in #5505 seems to cause the problem here - it was added to hold back then-existing documentation instances of mkdocs to 0.17.0. However the way it was set up, it kept the latest version to 1.0 (1.1 was in-dev during that time). 1.1 was released, and received bugfix releases since as well which regressed RTD at mkdocs documentations which does not pin the required versions to latest on their own.

[humitos]

However the way it was set up, it kept the latest version to 1.0 (1.1 was in-dev during that time).

We need to pin our dependencies in some way to try to make them deterministic. At some point those default will be outdated and we need to come up with a plan to update the default values. We have the same problem with Sphinx right now and it's not easy to update the versions and keep every user happy with the new default.

[stsewd]

@GraionDilach we recommend pinning to a specific version so your builds don't break if we update the default version, also if gives you a way to have the exact build locally.

[Mailaender]

An example of how a requirements.txt should actually look like would also be helpful. At the moment information is scattered around and after reading it all, I still don't understand how to update mkdocs per project.

[stsewd]

your requirements.txt file should be like

mkdocs==1.1.2

[Mailaender]

Thanks. I tried it. OpenHV/docs@0686167 but it regresses in terms of the table of contents and also doesn't fix the syntax highlighting as expected.

[stsewd]

Please report those problems to the mkdocs repo

[Mailaender]

Setting requirements.txt to

mkdocs==1.1.1

or

mkdocs==1.1

also didn't help. Only deleting requirements.txt reverted things back to normal. So I think it must be part of your dependency system where the breakage occurs.

[stsewd]

@Mailaender please link to your project and also see if you can replicate locally with the same version

[Mailaender]

See https://github.com/OpenHV/docs

https://readthedocs.org/projects/openhv/builds/

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[Zylann]

I also noticed a difference in my table of contents compared to the version of mkdocs I tested with locally.
When I tested locally, the theme shipped with mkdocs had working collapsible sections and highlights the current section, while the one I just built with RTD shows everything at once at the same level with no highlight of the current section.

I noticed the theme was part of mkdocs distribution so I decided to change the version in my requirements.txt, hoping I would get the same result on RTD:

mkdocs>=1.1.2

But the theme still looks different.

Strangely, in the build log, I can see this occurring:

python -m pip install --upgrade --no-cache-dir [...] mkdocs<1.1

And then this next:

python -m pip install --exists-action=w --no-cache-dir -r addons/zylann.hterrain/doc/requirements.txt

Which results in two installs of mkdocs?
The build: https://readthedocs.org/projects/hterrain-plugin/builds/12444767/

I'm trying to understand why my local install of mkdocs has great theme but not the one RTD built, despite them being supposed to use the same version :/

---

Update: somehow the theme now looks the same. I didn't change anything 🤷

[stsewd]

Update: somehow the theme now looks the same. I didn't change anything shrug

It may have been a cached page. Also, we install a default version of mkdocs, but you can install any version you require, that's why is installed twice, the second installation is the one being used.

[Zylann]

So even with latest version pinned, apparently the problem with mkdocs would actually come from RTD: mkdocs/mkdocs#2145 (comment)

docs_dir is being overriden somehow, because it doesn't properly defaults to its normal default value.
I had to explicitely set docs_dir: docs in mkdocs.yml (which is what it normally defaults to) to make it work.

[stsewd]

We set that value here if isn't present.

readthedocs.org/readthedocs/doc_builder/backends/mkdocs.py

Line 148 in 2dc9706

docs_dir = self.docs_dir(docs_dir=user_docs_dir)

I think maybe old versions of mkdocs didn't a default value? Still, if so the docs wouldn't build locally, so I think we shouldn't edit that setting. Another possibility is that this was added for users that didn't have a mkdocs.yaml file (think this may be the case actually) #2483.

[stsewd]

This fix should be live by next tuesday.

[stsewd]

@Zylann the fix is live now, if you want to give it a try :)

[Zylann]

I removed my workaround and it seems to work this time. Thank you!