backstage / backstage/mkdocs-monorepo-plugin
mkdocs_build_plantuml will not work when monorepo enabled
- 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
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