Roave / DocbookTool

:books: Docbook Tool for static documentation generation from Markdown files
52 stars 4 forks source link

Inlined external PUML breaks when PUML has an include #362

Open asgrim opened 4 months ago

asgrim commented 4 months ago

Issue description

When an external PlantUML diagram that itself has an include, such as:

@startuml
!include external-diagram.puml
@enduml

is included by way of an inline using \Roave\DocbookTool\Formatter\InlineExternalImages, since the diagram is written to a temporary path to be rendered by PlantUML in \Roave\DocbookTool\Formatter\RenderPlantUmlDiagramInline, it becomes disconnected from the original source tree, and therefore the !include directive cannot be resolved.

Example test case

Example reproducer in our test suite:

$ git diff --cached
diff --git a/test/fixture/docbook/diagram-with-include.puml b/test/fixture/docbook/diagram-with-include.puml
new file mode 100644
index 0000000..f393672
--- /dev/null
+++ b/test/fixture/docbook/diagram-with-include.puml
@@ -0,0 +1,4 @@
+@startuml
+!include external-diagram.puml
+Bob<-Alice : hello2
+@enduml
diff --git a/test/fixture/docbook/test.md b/test/fixture/docbook/test.md
index 8f3490b..c661eb5 100644
--- a/test/fixture/docbook/test.md
+++ b/test/fixture/docbook/test.md
@@ -66,3 +66,5 @@ They are hand drawn, that's why they look rubbish.
 ## Inline PUML file

 ![An external PlantUML diagram](./external-diagram.puml)
+
+![An external PlantUML diagram with an include](./diagram-with-include.puml)

Workaround

Suggested workaround for consumers who encounter this bug until fixed: copy the necessary diagrams into /tmp before build, e.g.:

FROM builder AS built

# Temporary workaround for https://github.com/Roave/DocbookTool/issues/362
RUN cp -rvf /docs-src/diagrams/* /tmp

RUN bin/docbook-tool --html --pdf