mkdocs build fails during GitHub Actions run, but works fine locally through Git Bash. What are possible causes?

[Andre601]

I encounter a rather strange behaviour with MkDocs, where building the site through GitHub Actions results in an error.
Meanwhile, building it locally on my PC works perfectly fine. I now try to find out what possible issues could be, so if one could help me understand the error would I really appreciate it.

Error

INFO    -  theme_overrides_manager: Theme overrides manager initialized
INFO    -  mkdocs_static_i18n: Building 'en' documentation to directory: /home/runner/work/Docs/Docs/site
INFO    -  DeprecationWarning: Do not access Theme._vars, instead access the keys of Theme directly.
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/mkdocs_static_i18n/reconfigure.py", line 304, in reconfigure_material_theme
    if "language" in config.theme._vars:
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/mkdocs/theme.py", line 87, in _vars
    warnings.warn(

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/runner/work/Docs/Docs/site
INFO    -  API-Docs-Generator: Found '[OAD' prefix. Parsing page...
ERROR   -  Error reading page 'en/api/index.md': No module named 'theme'
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.12.3/x64/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/mkdocs/__main__.py", line 284, in build_command
    build.build(cfg, dirty=not clean)
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/mkdocs/commands/build.py", line 310, in build
    _populate_page(file.page, config, files, dirty)
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/mkdocs/commands/build.py", line 163, in _populate_page
    page.markdown = config.plugins.on_page_markdown(
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/mkdocs/plugins.py", line 635, in on_page_markdown
    return self.run_event('page_markdown', markdown, page=page, config=config, files=files)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/mkdocs/plugins.py", line 566, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/Docs/Docs/theme/.hooks/api_docs_gen.py", line 18, in on_page_markdown
    return rx.sub(_replacer, markdown)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/Docs/Docs/theme/.hooks/api_docs_gen.py", line 26, in _replacer
    data, source=source, writer=Jinja2DocumentsWriter('theme')
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/openapidocs/mk/jinja.py", line 101, in __init__
    self._env = get_environment(package_name, views_style)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/openapidocs/mk/jinja.py", line 70, in get_environment
    loader = PackageLoader(package_name, templates_folder)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/site-packages/jinja2/loaders.py", line 291, in __init__
    import_module(package_name)
  File "/opt/hostedtoolcache/Python/3.12.3/x64/lib/python3.12/importlib/__init__.py", line 90, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1324, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'theme'
Error: Process completed with exit code 1.

Further Information:

• This started with a Dependabot PR bumping Material for MkDocs to 9.5.15. The update itself Bumps MkDocs to 1.6.0
• From my basic understanding is this most likely related to my hook used for Rest-API docs generation, using Essentials-OAPI. The Hook used can be found here and worked with the previous version of MkDocs.
• Following plugins are used:
  • Search
  • i18n (Note: I use a specific version from a branch that fixes an issue with the folder system or smth. See the requirements.txt file)
• The mkdocs.yml currently used can be found here

[pawamoy]

It looks like Jinja2DocumentsWriter('theme') continues with PackageLoader(package_name, templates_folder) where package_name="theme" and later import_module("theme") fails because there's no such module. Not sure why it fails after upgrading to MkDocs 1.6.0. You could reach out to the maintainers of openapidocs or tag them here.

[Andre601]

Actually, I think I know why it does work on PC: I simply haven't updated mkdocs there yet, so it's still using the latest 1.5.x version...

Also, not sure if tagging the OAPI devs is really the right plan here. The library used is not from them but by the devs of @Neoteroi which by the looks of it seems to be maintained by @RobertoPrevato, so I hope they have some clues here...

Maybe it's related to the fix oprypin made for hooks where the Syspath wasn't exposed? Like where you had to do the hack with

import sys, os
sys.path.insert(0, os.path.dirname(__file__))

[pawamoy]

I wrote openapidocs to refer to the Python package that provides this module, couldn't find the distribution name on PyPI 😅

I'd suggest to run some debug sessions (with breakpoints in your hooks) with both MkDocs 1.5 and 1.6 locally to see what changes between the two 🙂

[Andre601]

I sadly don't quite understand half of this...

[pawamoy]

I'm suggesting that you use a Python debugger to see what happens when you run your code on MkDocs 1.5 and 1.6. VSCode and PyCharm allow to do that. Other editors have their plugins too. Otherwise you can use pdb, from the standard lib: https://docs.python.org/3/library/pdb.html.

Have you been able to confirm that the issue happens locally with MkDocs 1.6?

[Andre601]

It happens locally with 1.6

[pawamoy]

OK, got it. Previously, MkDocs didn't touch to sys.path before and after executing a hook module. So when you inserted a path, this path stayed there for the whole run. Now, with MkDocs 1.6, any modification to sys.path in a hook module is reverted after the hook module was executed.

Since the functions defined in your hook are indeed executed after MkDocs has reverted sys.path to not contain the .hooks folder, by the time the package loader tries to find the theme module, its parent folder is not in sys.path anymore and the loader fails to find it.

Workaround: move the sys.path modification into the on_page_markdown function.

[Andre601]

This indeed fixed the issue. Thank you.

[Andre601]

Maybe it's worth pointing that out in the documentation that explains this change? Just so others may not get as confused by this.