Guide explaining how to keep compatibility with mkdocs #4726
Guide to help users that weren't pinning a version of
This guide helps them to keep building their docs on Read the Docs showing the workarounds needed.
I'm not really happy with the document and how it's written but I think it communicates what we need.
The text was updated successfully, but these errors were encountered:
What do you think about adding a warning note in https://docs.readthedocs.io/en/latest/builds.html#mkdocs (at the bottom of the section) like this:
.. warning:: We strongly recommend to :ref:`pin the MkDocs version <guides/specifying-dependencies:Specifying Dependencies>` used for your project to build the docs to avoid potential future incompatibilities.
This way, if the user select MkDocs for his docs we are warning and pointing him to the right section about how to specify a dependency (which in the near future will be able from the YAML without needing a requirements.txt file).
On the other hand, supposing that we would have had this note in that place, the error would have happened again since in this particular case we need to pin other packages also :/. This note, will be helpful under "some" circuntances only.
I don't really have a plan :(
It's hard to remove the time-sensitive information since the user does know anything about the MkDocs version installed right now (because it's done automatically by RTD). So, talking about "Migrating from 0.15 version to X.X" or similar doesn't make too much sense to me. They don't really know that they strictly depend on
I was thinking on this guide like a temporal solution to point users if they open issues around this and/or to communicate via email to our .com customers.
This guide could probably completely removed some months after we notify our users/customers I'd say since it will become useless.
I added a new commit for this.