How can i debug my environment where mkdocs and mike cannot find material-extensions even though it is installed?

[ritwika314]

Hi,

Note

I am adding this question as a discussion rather than an issue because I most likely made a mistake while setting my project up. I can use the deprecated emoji index to unblock my project for now, but i would like to use the updated packages.

I have the following list of extensions in my mkdocs.yml:

markdown_extensions:
  - admonition
  - abbr
  - attr_list
  - def_list
  - footnotes
  - meta
  - md_in_html
  - tables
  - toc:
      permalink: true
      title: On this page
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
     emoji_index: !!python/name:material.extensions.emoji.twemoji
     emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

When I run mkdocs serve or mike deploy, here is the error i run into immediately:

Error: MkDocs encountered an error parsing the configuration file: while constructing a Python object
cannot find module 'material.extensions.emoji' (No module named 'material.extensions')
  in "/Users/ritwika/bodo/docs/mkdocs.yml", line 95, column 19

Here's my environment:

Package                    Version
-------------------------- ----------
Babel                      2.14.0
certifi                    2024.2.2
charset-normalizer         3.3.2
click                      8.1.7
colorama                   0.4.6
ghp-import                 2.1.0
idna                       3.6
importlib-metadata         7.0.1
importlib_resources        6.1.2
Jinja2                     3.1.3
Markdown                   3.5.2
MarkupSafe                 2.1.5
mergedeep                  1.3.4
mike                       2.0.0
mkdocs                     1.5.3
mkdocs-autorefs            0.5.0
mkdocs-material            9.5.11
mkdocs-material-extensions 1.3.1
packaging                  23.2
paginate                   0.5.6
pathspec                   0.12.1
pip                        24.0
platformdirs               4.2.0
Pygments                   2.17.2
pymdown-extensions         10.7
pyparsing                  3.1.1
python-dateutil            2.8.2
PyYAML                     6.0.1
pyyaml_env_tag             0.1
regex                      2023.12.25
requests                   2.31.0
setuptools                 68.2.0
six                        1.16.0
urllib3                    2.2.1
verspec                    0.1.0
watchdog                   4.0.0
wheel                      0.41.2
zipp                       3.17.0

Any ideas on what may be causing this issue and pointers on how I can debug the build process in this environment? Should I try installing mkdocs-material and mike from source rather than pip?

[kamilkrzyskow]

Hello @ritwika314,
quite weird issue, especially if MkDocs does resolve the material theme name.

Firstly for a sanity-check you can do pip show mkdocs-material. It should display the path to the installed mkdocs-material module under Location: <path>. Then check inside of the <path>/material directory if you have the extensions folder with emoji.py and __init__.py files.

Perhaps your mkdocs uses a different site-packages directory than the one used with pip or python commands.
You can try running python -m mkdocs serve to see if there is another result.
You can also debug it with a hook add the hook to your mkdocs.yml config and inside the hook write (also remove the failing emoji settings from the config):

import sys
import os

for path in sys.path:
    print("sys path:", path)
    
import material

print("material file:", os.path.abspath(material.__file__))

import material.extensions as extensions

print("extensions file:", os.path.abspath(extensions.__file__))

it runs from top to bottom, so if there is a crash with extensions there should be still something printed above the traceback.

You can also run pip install mkdocs-material --force-reinstall to make sure everything gets reinstalled.

[ritwika314]

Thanks for the suggestions @kamilkrzyskow, I was able to debug my issue using them! Marking this as the answer.

What happened

As you suggested:

Perhaps your mkdocs uses a different site-packages directory than the one used with pip or python commands.

This is sort-of what happened. I was running my project in its own virtual environment, but my $PATH made the mkdocs serve command pick up a previous version in /usr/local/bin . Same issue with mike. I then did this:

You can try running python -m mkdocs build to see if there is another result.

and that rendered correctly. So i just specified the location to pick up mike to test whether it gave me the same issue:

(.mkdocs) ritwika@ritwikas-MacBook-Pro docs %  /Users/ritwika/doc_site/.mkdocs/bin/mike deploy dev_docs`

it worked, no issues 🎉 !

[kamilkrzyskow]

Hmm, installing mkdocs in the virtual environment should still make mkdocs run from there 🤔
In general I think it's a good idea to keep the global python site-packages clean of any dependencies to make sure you're using the one inside the virtual environment.
You can run pip freeze > r.txt, pip uninstall -r r.txt -y to remove everything.

[ritwika314]

In general I think it's a good idea to keep the global python site-packages clean of any dependencies to make sure you're using the one inside the virtual environment.

Agreed, cleaned it up to make sure i dont run into this again.