From 7147ac55a58476b2c1bf6dd628d93e8c6dbaf460 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 4 Oct 2018 11:06:18 +0200 Subject: [PATCH 1/4] Guide explaining how to keep compatibility with mkdocs --- docs/guides/mkdocs-old-versions.rst | 75 +++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/guides/mkdocs-old-versions.rst diff --git a/docs/guides/mkdocs-old-versions.rst b/docs/guides/mkdocs-old-versions.rst new file mode 100644 index 00000000000..3e4159b03af --- /dev/null +++ b/docs/guides/mkdocs-old-versions.rst @@ -0,0 +1,75 @@ +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. + +.. _upgrade the default version installed: https://github.com/rtfd/readthedocs.org/pull/4041 + +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 a specific version +* your project is using a custom theme +* your project is using Markdown extensions + +In case your builds are failing because of a ``mkdocs`` issue, +you may want to follow one of the following solutions depending on the case. + + +Pin mkdocs to the previous version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before Read the Docs upgraded its default version installed, ``mkdocs==0.15.0`` was used. +To make your project continue using this version you will need to create a ``requirements.txt`` file with this content:: + + # requirements.txt + mkdocs==0.15.0 + mkdocs-bootstrap==0.1.1 + mkdocs-bootswatch==0.1.0 + +.. note:: + + Most of the breaking changes where introduced in ``mkdocs==0.17``, + so you may want to test only pinning ``mkdocs`` to ``mkdocs<0.17`` + and check if your docs keep building successfully. + + +Upgrade your custom theme to be compatible with newer mkdocs versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible that event your build passes your documentation doesn't look correct. +This may be because the new ``mkdocs==0.17.3`` version installed by Read the Docs introduced some breaking changes on the structure of the theme. + +You should check the `mkdocs' Custom Theme documentation`_ to upgrade your custom theme and make it compatible with the new version. + +.. _mkdocs' Custom Theme documentation: https://www.mkdocs.org/user-guide/custom-themes/ + + +Upgrade how extension arguments are defined +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``mkdocs`` has changed the way that ``markdown_extensions`` are defined and you may need to upgrade it. +If you where passing arguments to the extension by defining them between brackets (``toc(permalink=true)``) in your ``mkdocs.yaml`` you may need to upgrade it to the new way. + +For example, this definition: + +.. code-block:: yaml + + markdown_extensions: + - admonition + - codehilite(guess_lang=false) + - toc(permalink=true) + - footnotes + - meta + +needs to be replaced by: + +.. code-block:: yaml + + markdown_extensions: + - admonition + - codehilite + guess_lang: false + - toc + permalink: true + - footnotes + - meta From 3960a08417d09988ac7bebfc843cb9211fc09a72 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 10 Oct 2018 16:52:28 +0200 Subject: [PATCH 2/4] Link to specifying dependencies document --- docs/guides/mkdocs-old-versions.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/guides/mkdocs-old-versions.rst b/docs/guides/mkdocs-old-versions.rst index 3e4159b03af..8080dc0380b 100644 --- a/docs/guides/mkdocs-old-versions.rst +++ b/docs/guides/mkdocs-old-versions.rst @@ -33,6 +33,9 @@ To make your project continue using this version you will need to create a ``req and check if your docs keep building successfully. +More detailed information about how to specify dependencies can be found :ref:`here `. + + Upgrade your custom theme to be compatible with newer mkdocs versions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From fdc39277daa0a38d3b9c6b4c3cf00e420690d5de Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 10 Oct 2018 16:53:47 +0200 Subject: [PATCH 3/4] Typo --- docs/guides/mkdocs-old-versions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/mkdocs-old-versions.rst b/docs/guides/mkdocs-old-versions.rst index 8080dc0380b..ccbd962f67c 100644 --- a/docs/guides/mkdocs-old-versions.rst +++ b/docs/guides/mkdocs-old-versions.rst @@ -1,7 +1,7 @@ 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. +Recent changes to ``mkdocs`` forced us to `upgrade the default version installed`_ by Read the Docs and this may be a breaking change for your documentation. .. _upgrade the default version installed: https://github.com/rtfd/readthedocs.org/pull/4041 From b2be8532a2a09420f49cde0f1f971602c2e52cc8 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 11 Oct 2018 10:01:24 +0200 Subject: [PATCH 4/4] Warning note to pin MkDocs requirements --- docs/builds.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/builds.rst b/docs/builds.rst index 5307dde9c7e..c5bdfc2f3ba 100644 --- a/docs/builds.rst +++ b/docs/builds.rst @@ -56,6 +56,12 @@ and MkDocs will build the ``.md`` files in that directory. As MkDocs doesn't support automatic PDF generation, Read the Docs cannot create a PDF version of your documentation with the *Mkdocs* option. +.. warning:: + + We strongly recommend to :ref:`pin the MkDocs version ` + used for your project to build the docs to avoid potential future incompatibilities. + + Understanding what's going on -----------------------------