Skip to content

Upgrade the version of mkdocs that readthedocs uses to one that isn't broken #9081

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.

Sign up for GitHub

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

Jump to bottom
Closed
mcarans opened this issue Apr 6, 2022 · 6 comments
Closed

Upgrade the version of mkdocs that readthedocs uses to one that isn't broken #9081

mcarans opened this issue Apr 6, 2022 · 6 comments
Labels
Improvement Minor improvement to code

Comments

@mcarans
Copy link

mcarans commented Apr 6, 2022 •
edited
Loading

Details

Failing build: https://readthedocs.org/projects/hdx-python-country/builds/16574497/

Fixed build with forced install of mkdocs 1.3.0:
https://readthedocs.org/projects/hdx-python-country/builds/16574520/

jinja2 3.1.0 breaks version of mkdocs before 1.2.4 and I get another error in my failing build "ImportError: cannot import name 'Sequence' from 'collections'". Both these errors are fixed by newer mkdocs.
@mcarans mcarans mentioned this issue Apr 6, 2022
Closed
@humitos
Copy link
Member

humitos commented Apr 6, 2022 •
edited
Loading

I think the error you are seeing is because you are using Python 3.10 together with mkdocs<1.1 (the version that RTD installs by default). It does work with 3.9, but it doesn't with 3.10

▶ python
Python 3.9.7 (default, Nov  3 2021, 12:39:37) 
[GCC 11.1.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from collections import Sequence, namedtuple
<stdin>:1: DeprecationWarning: Using or importing the ABCs from 'collections' instead of from 'collections.abc' is deprecated since Python 3.3, and in 3.10 it will stop working
>>>

We cannot easily upgrade the default version we are installing because there are a lot of projects that rely on that version. Then, if we upgrade the default mkdocs version, all those projects will be broken. We have been talking about writing a deprecation policy to allow us to move forward and keep the dependencies up to date, but we are not sure yet what's the best way to do it.

@humitos
Copy link
Member

humitos commented Apr 6, 2022

I just realized that we fixed the problem related to Jinjja for Sphinx 1.8.x (#9036) but we may need to do the same for MkDocs, cc @ericholscher

@mike-eason
Copy link

Can confirm, the issue occurs for me also. Here's a recent build.

Thank you.

@ericholscher
Copy link
Member

Thanks for writing in. You can install whatever version of mkdocs you'd like with our platform: https://docs.readthedocs.io/en/latest/guides/reproducible-builds.html#reproducible-builds

We will work to upgrade the default version however, since that's not a great experience to have it broken.

@jamiehewitt15
Copy link

I got this same error "ImportError: cannot import name 'Sequence' from 'collections'".

Forcing the build to install mkdocs 1.3.0 worked for me to solve this.

@bertsky bertsky mentioned this issue Jul 6, 2022
Closed
@stsewd stsewd added the Improvement Minor improvement to code label Aug 18, 2022
@humitos humitos mentioned this issue Dec 5, 2022
Closed
OwenPriceSkelly added a commit to Garden-AI/garden that referenced this issue May 17, 2023
@OwenPriceSkelly
workaround RTD pinning broken mkdocs
7f01b38 
see readthedocs/readthedocs.org#9081
RTD build secretly pins mkdocs <1.1, which is broken due to a jinja2
incompatibility.

This just tries to move the step that installs *our* dependencies (which
are compatible) after the step that automaticlally installs the wrong
version of some of them.
OwenPriceSkelly added a commit to Garden-AI/garden that referenced this issue May 19, 2023
@OwenPriceSkelly
early docs for developers (#136)
bd2bf8b 
* switch to mkdocs

* rough draft of docs with theme and extensions

* try tweaking readthedocs.yaml for PR hook

* workaround RTD pinning broken mkdocs

see readthedocs/readthedocs.org#9081
RTD build secretly pins mkdocs <1.1, which is broken due to a jinja2
incompatibility.

This just tries to move the step that installs *our* dependencies (which
are compatible) after the step that automaticlally installs the wrong
version of some of them.

* edit architecture overview, add code highlighting

* WIP reformatting docstrings for mkdocstrings

Still need to fix Garden's docstring

* fix docstrings for Garden, add to PR template

* flake8 gripes
ProfYaffle added a commit to tvheadend/tvheadend-documentation that referenced this issue Jun 14, 2023
@ProfYaffle
Update .readthedocs.yaml Python version
c4c5f41 
As per readthedocs/readthedocs.org#9081 - while the template suggests Python 3.11, this doesn't actually work with the version of mkdocs installed by default. 

Reverting to Python 3.9 apparently fixes it.
humitos added a commit that referenced this issue Jul 4, 2023
@humitos
Build: install all the latest Python "core requirements"
c063414 
I created a new feature flag called `INSTALL_LATEST_CORE_REQUIREMENTS` that does
not depend on any other feature flag. Its goal is to always install the latest
Python packages.

We are trying to move away from pinning the dependencies on our side and telling
users to do that on their side if they want to have reproducible builds over
time.

I think this is the best outcome for new projects since they will immediately
use the latest versions of everything instead of old (and maybe broken)
dependencies.

I propose to set a particular date for this feature flag and make new projects
to start building with all the latest dependencies. This will, at least, stop
making the problem bigger. Later, we can decide how to communicate to old
projects that we are going to install the latest requirements and if they don't
want that, they should pin their dependencies. We can follow our new and shiny
deprecation path we have built and tested in the last month.

Related readthedocs/meta#8
Related #9562
Related #10402
Related #9081
@humitos humitos mentioned this issue Jul 4, 2023
Merged
humitos added a commit that referenced this issue Jul 12, 2023
@humitos
Build: install all the latest Python "core requirements" (#10508)
cd498b5 
* Build: install all the latest Python "core requirements"

I created a new feature flag called `INSTALL_LATEST_CORE_REQUIREMENTS` that does
not depend on any other feature flag. Its goal is to always install the latest
Python packages.

We are trying to move away from pinning the dependencies on our side and telling
users to do that on their side if they want to have reproducible builds over
time.

I think this is the best outcome for new projects since they will immediately
use the latest versions of everything instead of old (and maybe broken)
dependencies.

I propose to set a particular date for this feature flag and make new projects
to start building with all the latest dependencies. This will, at least, stop
making the problem bigger. Later, we can decide how to communicate to old
projects that we are going to install the latest requirements and if they don't
want that, they should pin their dependencies. We can follow our new and shiny
deprecation path we have built and tested in the last month.

Related readthedocs/meta#8
Related #9562
Related #10402
Related #9081

* Build: remove deprecated dependencies

* Build: install latest core requirements when using Conda

* Docs: update default versions documentation to match the changes

* Feedback from review

Do not install `sphinx-rtd-theme` and clarify the docstring.

* Update documentation
@humitos
Copy link
Member

humitos commented Jul 12, 2023

Starting on August 7, Read the Docs will start installing the latest MkDocs version available. See https://blog.readthedocs.com/python-core-requirements-changed/

@humitos humitos closed this as completed Jul 12, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Improvement Minor improvement to code
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@ericholscher @humitos @mcarans @stsewd @mike-eason @jamiehewitt15