backstage / backstage/mkdocs-monorepo-plugin
Windows build fails when using slashes in site_name
- Dominant language
- Python
- Stars
- 400
- Forks
- 80
- PR merge metrics
- No merged PRs in 30d
Description
I have a monorepo setup. Since I have quite a lot of packages the documentation started to get messy and I wanted to break it down a bit more. This is how in a submodule the mkdocs.yml looks like:
```yml
site_name: instruments/midas-adam-switch
```
This works without problems on linux systems, however we also have devs on windows and there it seems the slash is causing problems:
```sh
ERROR - Error reading page 'instruments/midas-adam-switch/api/adam.md': join() missing 1 required positional argument: 'path'
Traceback (most recent call last):
...
File "C:\Users\rubigi\git\midas\.venv\lib\site-packages\mkdocs_monorepo_plugin\edit_uri.py", line 39, in __get_page_dir_alias
alias = path.join(*parts)
TypeError: join() missing 1 required positional argument: 'path'
```
So the error originates from [here](https://github.com/backstage/mkdocs-monorepo-plugin/blob/f62ae22e387c1cb2ef358a0a74926400d3d8021f/mkdocs_monorepo_plugin/edit_uri.py#L33).
I added some print statements to the file in my venv to have some example output:
```py
def __get_page_dir_alias(self):
parts = self.page.url.split("/")
print(f'{self.plugin.aliases.keys()=}')
while True:
print(f'{parts=}')
parts.pop()
alias = path.join(*parts)
print(f'{alias=}')
if alias in self.plugin.aliases:
return alias
```
Which outputs:
```
self.plugin.aliases.keys()=dict_keys(['instruments/midas-adam-switch'])
parts=['instruments', 'midas-adam-switch', 'api', 'adam', '']
alias='instruments\\midas-adam-switch\\api\\adam'
parts=['instruments', 'midas-adam-switch', 'api', 'adam']
alias='instruments\\midas-adam-switch\\api'
parts=['instruments', 'midas-adam-switch', 'api']
alias='instruments\\midas-adam-switch'
parts=['instruments', 'midas-adam-switch']
alias='instruments'
parts=['instruments']
```
The fix is actually quite simple, normalize the windows backslashes:
```py
def __get_page_dir_alias(self):
parts = self.page.url.split("/")
while True:
parts.pop()
alias = path.join(*parts).replace("\\", "/")
if alias in self.plugin.aliases:
return alias
```
Which fixes the pathing on windows. I tested the fix on both linux and windows and it worked for me in both cases. I would be willing to open a pr to address this, but wanted to create an issue first to discuss 😄
Contributor guide
Research direction
Start in mkdocs_monorepo_plugin/edit_uri.py at __get_page_dir_alias and reproduce the reported site_name case on Windows and Linux. Verify that aliases containing slashes are found consistently and that the documented monorepo build completes without the join() error.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100