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
319 stars 74 forks source link

Can you make the monorepo plugin compatible with the mkdocs D2 plugin? #131

Open jal7027 opened 4 months ago

jal7027 commented 4 months ago

I'm trying to integrate docs that use the mkdocs-d2-plugin into a Backstage Techdocs docs site. Could you look into the errors and see if it's possible to make these packages compatible?

When I attempt to install mkdocs, mkdocs-d2-plugin and mkdocs-monorepo-plugin using poetry, I get a version solving error:

joseph.leiber  % poetry add mkdocs mkdocs-techdocs-core mkdocs-d2-plugin
Using version ^1.6.0 for mkdocs
Using version ^1.3.5 for mkdocs-techdocs-core
Using version ^1.3.4 for mkdocs-d2-plugin

Updating dependencies
Resolving dependencies... (0.2s)

Because no versions of mkdocs-techdocs-core match >1.3.5,<2.0.0
 and mkdocs-techdocs-core (1.3.5) depends on mkdocs-material (9.5.13), mkdocs-techdocs-core (>=1.3.5,<2.0.0) requires mkdocs-material (9.5.13).
And because mkdocs-material (9.5.13) depends on mkdocs (>=1.5.3,<1.6.0), mkdocs-techdocs-core (>=1.3.5,<2.0.0) requires mkdocs (>=1.5.3,<1.6.0).
So, because minimal depends on both mkdocs (^1.6.0) and mkdocs-techdocs-core (^1.3.5), version solving failed.

If I bypass the version solving warning and attempt to install the packages using pip and run mkdocs serve, I get an quite lengthy TypeError that seems to be rooted in the monorepo plugin itself, according to Traceback.

Here's the truncated error:

INFO    -  Building documentation...
INFO    -  mkdocs-d2-plugin: Using cache at .cache/plugin/d2/db (dbm.ndbm)
INFO    -  Cleaning site directory
ERROR   -  Error reading page 'index.md': join() missing 1 required positional argument: 'a'
Traceback (most recent call last):
  File "/Users/joseph.leiber/Library/Caches/pypoetry/virtualenvs/minimal-sCI7Dks--py3.12/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
 ...
 ...
 ...
  File "/Users/joseph.leiber/Library/Caches/pypoetry/virtualenvs/minimal-sCI7Dks--py3.12/lib/python3.12/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'

An odd note is that I'm able to run all of this without errors on a GitHub runner, but the D2 plugin fails to generate an SVG - it just renders a fenced D2 codeblock in text. In other words, it just fails silently.

On the runner, I'm using Python 3.11.5, mkdocs-techdocs-core==1.3.5, mkdocs-monorepo-plugin==1.1.0, and the latest mkdocs-d2-plugin.