Guide explaining how to keep compatibility with mkdocs

[humitos]

Guide to help users that weren't pinning a version of mkdocs but were relying on mkdocs==0.15. Since we upgrade our default version installed, they will find that their docs are not building anymore.

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.

Related to #4041 and #4556

[stsewd]

Just left some comments

[stsewd]

We use title case for titles

[stsewd]

an -> a

[humitos]

@stsewd thanks! I took your comments.

[humitos]

@davidfischer please, when you have some time, take a look at this PR since you were helping me to understand the underlying problem and find the solution.

[davidfischer]

Overall, this guide is a good one. I do have a few thoughts:

• We should probably strongly recommend that people pin versions of mkdocs. The same problem may arise when we upgrade from 0.17 -> 1.x.
• This guide has time-sensitive information. In a year, this guide will probably not be needed and in 2 years it definitely won't be. What's the plan for deprecating and removing it?
• We should crosslink to the docs for specifying requirements

[davidfischer]

on -> to

[davidfischer]

I actually couldn't find exactly where this syntax changed. I tested building docs with the old method in 0.15 and they still didn't build. Maybe this was a change in a markdown parser? I'm not sure.

[humitos]

Did you pin Markdown also to some version? I didn't, and I had to upgrade this.

[davidfischer]

Got it. Maybe this changed underneath mkdocs.

[humitos]

Good points!

• We should probably strongly recommend that people pin versions of mkdocs. The same problem may arise when we upgrade from 0.17 -> 1.x.

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.

• This guide has time-sensitive information. In a year, this guide will probably not be needed and in 2 years it definitely won't be. What's the plan for deprecating and removing it?

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 0.15.

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.

• We should crosslink to the docs for specifying requirements

I added a new commit for this.

[davidfischer]

What do you think about adding a warning note

Sounds good to me.