mkdocs-git-committers-plugin-2 has an invalid wheel [was: Changes in MkDocs v1.4.0 causing deploy error]

[josh-wong]

Issue

I attempted to deploy a docs site built on Material for MkDocs v8.5.5 with mkdocs-git-committers-plugin-2 installed. However, the following error occurs:

ERROR: mkdocs-git-committers-plugin-2 has an invalid wheel, mkdocs-git-committers-plugin-2 has an invalid wheel, multiple .dist-info directories found: mkdocs_git_committers_plugin-0.2.2.dist-info, mkdocs_git_committers_plugin_2-0.2.2.dist-info

Screenshot

Troubleshooting

I've confirmed that the error does not occur when deploying docs sites built on Material for MkDocs v8.5.4, which is based on a version of MkDocs prior to v1.4.0.

As mentioned in the section "Upgrades for plugin developers" of the release notes for MkDocs v1.4.0, I think the changes to how MkDocs v1.4.0 and later handle plugins are causing this error. However, I'm not experienced nor knowledgeable enough to even try to make the changes on my own🙇🏻‍♂️

[ojacques]

Thanks for the detailed report @josh-wong !

From the error message, it looks like two versions of the plugin were installed: mkdocs-git-committers-plugin and mkdocs-git-committers-plugin-2.
Try uninstalling mkdocs-git-committers-plugin (with pip uninstall mkdocs-git-committers-plugin ).
If you are using a python virtual environment, you can try to wipe it and install from scratch again.

I will double check in parallel if there is an incompatibility with mkdocs 1.4.0.

Let me know.

[josh-wong]

From the error message, it looks like two versions of the plugin were installed: mkdocs-git-committers-plugin and mkdocs-git-committers-plugin-2.

Thanks for the additional troubleshooting pointers, @ojacques!

I thought that reference to mkdocs-git-committers-plugin in the error message was a bit odd too since my .yaml file for installing MkDocs plugins via pip only specifies mkdocs-git-committers-plugin-2 to be installed. For example:

- run: pip install \ 
          git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git \
          mkdocs-video \
          mkdocs-git-revision-date-localized-plugin \
          python-slugify \
          mkdocs-git-committers-plugin-2 \
          mkdocs-rss-plugin \

Example source: josh-wong/bitcoin-cash-node-on-raspberry-pi/.github/workflows/ci.yml

Also, just to clarify since my ci.yml file mentioned above shows the Material for MkDocs Insiders repository, I've confirmed that the issue happens on both the standard Material for MkDocs repository and the Insiders version when using the latest versions (v8.5.5). When specifying the version prior for both the standard Material for MkDocs v8.5.4 and mkdocs-material-insiders v8.5.4, mkdocs-git-committers-plugin-2 works as expected without errors when deploying the page through GitHub.

Try uninstalling mkdocs-git-committers-plugin (with pip uninstall mkdocs-git-committers-plugin ).
If you are using a python virtual environment, you can try to wipe it and install from scratch again.

Sorry, I should have specified that I'm deploying the site using GitHub Pages, which is where I'm encountering the error.

When serving the site locally, the site builds fine without encountering the error (although contributors aren't show on the locally built site, but I don't clearly remember if the contributors were displaying before). Locally, I can confirm that I've installed the latest version of mkdocs-git-committers-plugin-2 and don't have mkdocs-git-committers-plugin installed.

I'll also do a little poking around to see what could be causing the issue and share any notes.

[ojacques]

@josh-wong, I found out that specifying a more restricted version range does work for mkdocs-git-committers-plugin-2.

- run: pip install \ 
          git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git \
          mkdocs-video \
          mkdocs-git-revision-date-localized-plugin \
          python-slugify \
          mkdocs-git-committers-plugin-2>=1.1.1 \
          mkdocs-rss-plugin \

Yes, your build does not seem to work entirely. Something with the RSS plugin. You may want to have a look around
https://github.com/squidfunk/mkdocs-material/blob/master/.github/workflows/documentation.yml#L59-L66

[Edit] for RSS plugin, see this thread

[oprypin]

So to be clear, it seems like this is nothing about "Changes in MkDocs v1.4.0".

[ojacques]

So to be clear, it seems like this is nothing about "Changes in MkDocs v1.4.0".

True. I changed the title.

[josh-wong]

Thanks a bunch, @ojacques! I've disabled mkdocs-rss-plugin since I was still in the early stages of using it.

And apologies for the busy work. I hope you can understand that, from my side, it looked like the changes to plugins in MkDocs v1.4.0 caused mkdocs-git-committers-plugin-2 to break.

For future reference, I'll make a note to myself about how changes to MkDocs may cause conflict with other plugins just to avoid banging on the wrong door😅

[oprypin]

Again,.. it's not about changes to MkDocs.
MkDocs 1.4.0 could've been released as an exact copy of the previous release and the rss plugin would've broken just the same, because it chooses to, based on the version number (see issue I just cross-linked)

[josh-wong]

Thanks for the explanation, @oprypin!

Again,.. it's not about changes to MkDocs.

I understand that, but please see it from my angle (as a non-developer) that, after MkDocs v1.4.0 got released with changes to how plugins are implemented, a plugin breaks and I have to assume which one is broken simply by judging the contents of the error message. Based on that error mesage, I assumed that mkdocs-git-committers-plugin-2 had broken, so I wanted to notify @ojacques just in case.

I know it's hard to coordinate all plugin developers to update or follow standard conventions, so I appreciate your work in testing plugins when releasing new versions of MkDocs🙌

[ojacques]

No worries @josh-wong - thanks again for a great report. Feel free to do one again if you suspect something with this plugin!