Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Guide explaining how to keep compatibility with mkdocs #4726

Merged
merged 4 commits into from Oct 12, 2018

Conversation

@humitos
Copy link
Member

@humitos humitos commented Oct 4, 2018

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

@humitos humitos requested a review from Oct 4, 2018
@humitos humitos force-pushed the humitos/guides/mkdocs-old-version branch from a01c249 to 83f5600 Oct 4, 2018
Copy link
Member

@stsewd stsewd left a comment

Just left some comments

@@ -0,0 +1,75 @@
Keep building docs with old version of MkDocs
Copy link
Member

@stsewd stsewd Oct 4, 2018

We use title case for titles


You should check that your docs continue building in any of these cases:

* your project doesn't have a ``requirements.txt`` file pinning ``mkdocs`` to an specific version
Copy link
Member

@stsewd stsewd Oct 4, 2018

an -> a

@humitos humitos force-pushed the humitos/guides/mkdocs-old-version branch from 83f5600 to 7147ac5 Oct 4, 2018
@humitos
Copy link
Member Author

@humitos humitos commented Oct 4, 2018

@stsewd thanks! I took your comments.

@humitos humitos requested a review from davidfischer Oct 9, 2018
@humitos
Copy link
Member Author

@humitos humitos commented Oct 9, 2018

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

Copy link
Contributor

@davidfischer davidfischer left a comment

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

Keep Building Docs With Old Version Of MkDocs
=============================================

Recent changes on ``mkdocs`` forced us to `upgrade the default version installed`_ by Read the Docs and this may be a breaking change for your documentation.
Copy link
Contributor

@davidfischer davidfischer Oct 9, 2018

on -> to

Upgrade how extension arguments are defined
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Copy link
Contributor

@davidfischer davidfischer Oct 9, 2018

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.

Copy link
Member Author

@humitos humitos Oct 10, 2018

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

Copy link
Contributor

@davidfischer davidfischer Oct 10, 2018

Got it. Maybe this changed underneath mkdocs.

@humitos humitos force-pushed the humitos/guides/mkdocs-old-version branch from 27fe741 to fdc3927 Oct 10, 2018
@humitos
Copy link
Member Author

@humitos humitos commented Oct 10, 2018

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
Copy link
Contributor

@davidfischer davidfischer commented Oct 10, 2018

What do you think about adding a warning note

Sounds good to me.

@humitos humitos merged commit 8c7e18d into master Oct 12, 2018
1 check passed
@humitos humitos deleted the humitos/guides/mkdocs-old-version branch Oct 12, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

3 participants