search

backstage / mkdocs-monorepo-plugin

✚ Build multiple documentation folders in a single Mkdocs. Designed for large codebases.
https://backstage.github.io/mkdocs-monorepo-plugin/
Apache License 2.0
312 stars 75 forks source link

Error since pull request #74 #77

Open gnaegi opened 2 years ago

gnaegi commented 2 years ago

Hi

I just updated the monorepo plugin and the before working project now fails to serve/build. I could drill down the issue to the pull request #74 which added the edit_uri.py file.

When I comment the call set_edit_url(config, page, self) in the file plugin.py on line 71 the project builds fine.

The edit_uri is not set in my environment and even when setting it something it does not build. The problem seems to have a dependency to the mkdocs-static-i18n plugin that we also use. I don't know if the root cause of the problem is in th2 i18n plugin or in the mono repo plugin. The issue occured after updating the monorepo plugin.

It would be great if you could add some check to the code to skip the edit-url thing when there is no edit-url set to fix this for cases like mine. Below I attached the Treaceback to narrow the issue.

What do you think?

Thanks for your work and thoughts about this issue

Regards Florian

ERROR    -  Error reading page 'manual_dev/index.md': join() missing 1 required positional argument: 'a'
Traceback (most recent call last):
  File "/opt/homebrew/Cellar/python@3.9/3.9.12/Frameworks/Python.framework/Versions/3.9/lib/python3.9/runpy.py", line 197, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/opt/homebrew/Cellar/python@3.9/3.9.12/Frameworks/Python.framework/Versions/3.9/lib/python3.9/runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/__main__.py", line 236, in <module>
    cli()
  File "/opt/homebrew/lib/python3.9/site-packages/click/core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "/opt/homebrew/lib/python3.9/site-packages/click/core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "/opt/homebrew/lib/python3.9/site-packages/click/core.py", line 1659, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/opt/homebrew/lib/python3.9/site-packages/click/core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/homebrew/lib/python3.9/site-packages/click/core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/__main__.py", line 181, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 63, in serve
    config = builder()
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 58, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/commands/build.py", line 317, in build
    config['plugins'].run_event('post_build', config=config)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/plugins.py", line 104, in run_event
    result = method(**kwargs)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs_static_i18n/plugin.py", line 622, in on_post_build
    _populate_page(file.page, config, files, dirty)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/commands/build.py", line 163, in _populate_page
    page = config['plugins'].run_event(
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs/plugins.py", line 102, in run_event
    result = method(item, **kwargs)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs_monorepo_plugin/plugin.py", line 71, in on_pre_page
    set_edit_url(config, page, self)
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs_monorepo_plugin/edit_uri.py", line 104, in set_edit_url
    page.edit_url = edit_url.build()
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs_monorepo_plugin/edit_uri.py", line 97, in build
    if self.__has_repo():
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs_monorepo_plugin/edit_uri.py", line 85, in __has_repo
    page_config_file_yaml = self.__get_page_config_file_yaml()
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs_monorepo_plugin/edit_uri.py", line 80, in __get_page_config_file_yaml
    abs_page_config_file_path = self.__get_page_config_file_path()
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs_monorepo_plugin/edit_uri.py", line 51, in __get_page_config_file_path
    alias = self.__get_page_dir_alias()
  File "/opt/homebrew/lib/python3.9/site-packages/mkdocs_monorepo_plugin/edit_uri.py", line 35, in __get_page_dir_alias
    alias = path.join(*parts)
TypeError: join() missing 1 required positional argument: 'a'
gnaegi commented 2 years ago

More info on this: with the introduction of edit_uri.py an incompatibility with the mkdocs-static-i18n has been introduced. The problem is that the mkdocs-static-i18n plugin generates pages for each languages starting with the language code (e.g. /en/yourmodule/yourpage/). The monorepo code in edit_uri.py can not resolve this page uri because it does interpret the language code as a site which can not resolved as it does not exist on disk. Revolving the alias and the yaml page fail.

Simply put: monorepo is not compatible anymore with the i18n plugin.

As an ugly workaround I created empty fake sites for each languages that with the magic '' trick don't appear in the navigation with an empty doc directory and an empty yaml file. What bothers me is that we do not use the edit_uri feature at all and the code that triggers the problem is only there to calculate the edit_uri.

Example for our workarond: https://github.com/OpenOLAT/OpenOLAT-docs/blob/master/mkdocs.yml https://github.com/OpenOLAT/OpenOLAT-docs/blob/master/sites/de/mkdocs.yml https://github.com/OpenOLAT/OpenOLAT-docs/blob/master/sites/en/mkdocs.yml

Another solution would be highly appreciated: either check for the i18n plugin (e.g. config["plugins"]["i18n"] or don't check for edit_uri at all if not set in the main yaml file.

bautrey37 commented 1 year ago

I have this error as well, except I am not using the i18n plugin. I'm using the https://github.com/wtc-cloud-eng/mkdocs-terraform-monorepo-plugin plugin which is built on top of this plugin.

tjpalmer commented 1 year ago

Same error for me.

And I'm unsure how to work around it (no i18n plugin for me, either).

tjpalmer commented 1 year ago

Backdating to version 1.0.0 seems to work.

margueritepd commented 2 months ago

This happens to me when I have a tree like this:

├── docs
│   └── ...
├── my-site-1
│   ├── docs -> ../docs
│   └── mkdocs.yml
├── my-site-2
│   ├── docs -> ../docs
│   └── mkdocs.yml
├── mkdocs.yml

and I run techdocs-cli generate --no-docker or mkdocs build from within my-site-1 or my-site-2. Because the absolute path of the site-specific mkdocs.yml is not contained in the absolute real (resolved) path of the doc markdown files, the code makes it to here and then here but the url is just '' so splitting it fails.

Maybe having the above layout doesn't make sense for a user of this plugin. However, I am an accidental user of this plugin, not an intentional one, because this comes baked into the backstage-core plugins. That being the case, it'd be nice for this plugin to work with my setup.