backstage / backstage/mkdocs-monorepo-plugin

mkdocs_build_plantuml will not work when monorepo enabled

Open
#48 1 comment 0 reactions 0 assignees View on GitHub
bug
Dominant language
Python
Stars
400
Forks
80
PR merge metrics
No merged PRs in 30d

Description

Dear all,

I find find out that plugin https://github.com/christo-ph/mkdocs_build_plantuml will not work correctly with monorepo.
Problem is that generated SVG/PNG will not be moved to the source folder. Related ticket https://github.com/christo-ph/mkdocs_build_plantuml/issues/9

How to reproduce:
1. Enable monorepo and plantuml build:
```yaml
theme:
name: 'material'

site_dir: source

plugins:
- build_plantuml:
render: "local"
bin_path: "/usr/bin/plantuml"
output_format: "svg"
diagram_root: "docs/diagrams"
output_folder: "out"
input_folder: "src"
- monorepo
```
2. Create puml file in `docs\diagrams\src\`, e.g. `system_quick_overview.puml` with content:
```
@startuml
Bob -> Alice : hello
@enduml
```
3. Run build.
```bash
mkdocs build
INFO - Cleaning site directory
INFO - Building documentation to directory: /source
INFO - Number headings up to level 3.
INFO - Generate a table of contents up to heading level 2.
INFO - Generate a cover page with "default_cover.html.j2".
INFO - Converting alignment(workaround).
ERROR - Failed to load image at "file:///source/catalog/diagrams/out/system_quick_overview.svg" (URLError: )
INFO - Documentation built in 10.39 seconds
Converting /docs/diagrams/src/system_quick_overview.puml

ls -laR source/diagrams
./source/diagrams:
total 12
drwxr-xr-x 3 root root 4096 May 17 13:31 .
drwxr-xr-x 15 root root 4096 May 17 13:31 ..
drwxr-xr-x 2 root root 4096 May 17 13:31 src
./source/diagrams/src:
total 12
drwxr-xr-x 2 root root 4096 May 17 13:31 .
drwxr-xr-x 3 root root 4096 May 17 13:31 ..
-rw-r--r-- 1 root root 474 May 17 13:31 system_quick_overview.puml

# NO Folder "out"
```
Nether folder, or files inside will be moved to source folder. But they exist in docs folder:
```bash
ls -laR /docs/diagrams
./docs/diagrams:
total 16
drwxrwxrwx 4 root root 4096 May 17 13:30 .
drwxrwxrwx 12 root root 4096 May 17 13:05 ..
drwxr-xr-x 2 root root 4096 May 17 13:30 out
drwxrwxrwx 2 root root 4096 May 17 13:05 src
./docs/diagrams/out:
total 16
drwxr-xr-x 2 root root 4096 May 17 13:30 .
drwxrwxrwx 4 root root 4096 May 17 13:30 ..
-rw-r--r-- 1 root root 6884 May 17 13:31 system_quick_overview.svg
./docs/diagrams/src:
total 12
drwxrwxrwx 2 root root 4096 May 17 13:05 .
drwxrwxrwx 4 root root 4096 May 17 13:30 ..
-rw-rw-rw- 1 root root 474 May 17 13:05 system_quick_overview.puml
```
4. Disable monorepo and run build. Test that it succeed.
```bash
mkdocs build
INFO - Cleaning site directory
INFO - Building documentation to directory: /source
INFO - Number headings up to level 3.
INFO - Generate a table of contents up to heading level 2.
INFO - Generate a cover page with "default_cover.html.j2".
INFO - Converting alignment(workaround).
INFO - Documentation built in 20.54 seconds
Converting /docs/diagrams/src/system_quick_overview.puml

ls -la source/diagrams
./source/diagrams:
total 16
drwxr-xr-x 4 root root 4096 May 17 13:34 .
drwxr-xr-x 15 root root 4096 May 17 13:34 ..
drwxr-xr-x 2 root root 4096 May 17 13:34 out
drwxr-xr-x 2 root root 4096 May 17 13:34 src
./source/diagrams/out:
total 16
drwxr-xr-x 2 root root 4096 May 17 13:34 .
drwxr-xr-x 4 root root 4096 May 17 13:34 ..
-rw-r--r-- 1 root root 6884 May 17 13:34 system_quick_overview.svg #THIS IS A FILE
./source/diagrams/src:
total 12
drwxr-xr-x 2 root root 4096 May 17 13:34 .
drwxr-xr-x 4 root root 4096 May 17 13:34 ..
-rw-r--r-- 1 root root 474 May 17 13:34 system_quick_overview.puml
```

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the issue with the provided MkDocs configuration, PlantUML inputs, and `mkdocs build`, first with monorepo enabled and then disabled. Trace where generated files are written and compare the expected `source/catalog/diagrams/out` path with the observed `docs/diagrams/out` path; done means the monorepo build completes without the missing-image error and places the generated image in the site directory.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.