Closed jvmlet closed 1 year ago
and globals.iuml resides in the same folder as myDiagramm.puml, which is partials/uml
Technically, this is not the correct location. From the Antora documentation:
Partials are resources that contain content snippets, such as common descriptions, terminology, or reference tables, that you plan to reuse in one or more pages. Partials are saved as AsciiDoc source files (.adoc) and stored in a partials directory.
https://docs.antora.org/antora/2.3/partials-directory/#partials
I think you should store them in examples
: https://docs.antora.org/antora/2.3/examples-directory/
Anyway, could you please share how do you reference myDiagramm.puml
in your AsciiDoc file?
It won't work if you are referencing your diagram as follows:
modules/ROOT/examples/hello.puml
@startuml
!include globals.iuml
Guillaume -> Alexander : Hello!
@enduml
modules/ROOT/examples/globals.iuml
skinparam monochrome true
skinparam ranksep 20
skinparam dpi 150
skinparam arrowThickness 0.7
skinparam packageTitleAlignment left
skinparam usecaseBorderThickness 0.4
skinparam defaultFontSize 12
skinparam rectangleBorderThickness 1
modules/ROOT/pages/index.adoc
[plantuml]
----
include::example$hello.puml[]
----
The reason is that the include::
directive in AsciiDoc is a preprocessor directive, so it's equivalent to:
modules/ROOT/pages/index.adoc
[plantuml]
----
@startuml
!include globals.iuml
Guillaume -> Alexander : Hello!
@enduml
----
As you can see, we cannot resolve globals.iuml
from the modules/ROOT/pages/index.adoc
because we don't have any context. The best we can do is try to resolve globals.iuml
relative to index.adoc
.
One workaround is to use the kroki-plantuml-include-paths
attribute.
For instance, you could define something like:
antora.yml
name: doc-site
title: Documentation Site
version: master
start_page: ROOT:index.adoc
nav:
- modules/ROOT/nav.adoc
asciidoc:
attributes:
kroki-plantuml-include-paths: './docs/modules/ROOT/examples'
Here, I'm using a relative path but you can also use an absolute path.
Alternatively, you could do something like:
modules/ROOT/pages/index.adoc
[plantuml]
----
include::example$globals.iuml[]
include::example$hello.puml[]
----
Thanks for your replay, @Mogztter
I can't use alternative approach , because hello.puml
won't be rendered by IDE
Setting kroki-plantuml-include-paths
also fails with the same error :
asciidoc:
attributes:
kroki-plantuml-include-paths: './docs/modules/ROOT/examples'
I'm using plantuml::{examplesdir}/myDiagramm.puml[]
from the adoc
file
Both myDiagramm.puml
and globals.iuml
are under ROOT/examples
dir
Setting kroki-plantuml-include-paths also fails with the same error :
The value depends on your directory structure. In my case, I'm running antora
at the root of the project and I have the following directory structure:
docs
├── antora.yml
└── modules
└── ROOT
└─── examples
├── globals.iuml
└── hello.puml
I'm using plantuml::{examplesdir}/myDiagramm.puml[] from the adoc file
The problem is that {examplesdir}/myDiagramm.puml
(or example$myDiagramm.puml
) relies on a virtual filesystem: https://docs.antora.org/antora/2.3/organize-content-files/#antoras-virtual-filesystem
I don't know if we can resolve !include globals.iuml
, we might be able to prefix globals.iuml
with example$
and ask Antora to resolve it... Can't make any promise but I will take a closer look.
What is certain is that include::example$hello.puml[]
won't work, you need to use plantuml::{examplesdir}/hello.puml[]
.
@wouter-veeken Please open a new issue. Antora is using a virtual file system, I don't think that's the case for Gatsby.
In any case, it might be the same consequence but probably not the same cause.
Hello,
I may be wrong, but the workaround (setting kroki-plantuml-include-paths
attribute) doesn’t seem to work for Structurizr diagrams !include
directive. Does it?
If I understand the code correctly, I’d say that include
preprocessing isn’t done for Structurizr diagrams, right?
https://github.com/Mogztter/asciidoctor-kroki/blob/38715518c590222e033cb39a152d0ad18ae51704/src/asciidoctor-kroki.js#L73-L84
Hello Yann,
Yes that's correct. For now, we preprocess PlantUML and VegaLite diagrams (to some extent).
The attribute kroki-plantuml-include-paths
is specific for PlantUML diagrams and won't have any effect on Structurizr diagrams.
Hello,
I'm trying to get diagrams with "plantuml fragments (separated .iuml files)" through Antora. I tried the workaround setting the "kroki-plantuml-include-paths" attribute, specifying a relative path but I failed generating the documentation. In order to explain what I did, I created repositories in order to expose the issue I get which is logged during the Antora generation.
Here is the error I got during the generation process :
$ npx antora generate --stacktrace --log-level=all --fetch antora-playbook.yml
[clone] https://github.com/jay-blanc/antora-doc-asciidoc.git [###############################################################################################################################]
[clone] https://github.com/jay-blanc/antora-doc-asciidoc-plantuml-simple.git [###############################################################################################################################]
[clone] https://github.com/jay-blanc/antora-doc-asciidoc-plantuml-iuml.git [###############################################################################################################################]
[14:37:29.095] INFO (asciidoctor): Skipping preprocessing of PlantUML include, because reading the referenced local file 'class_a.iuml' caused an error:
Error: ENOENT: no such file or directory, open 'class_a.iuml'
file: modules/ROOT/pages/diag-class.adoc
source: https://github.com/jay-blanc/antora-doc-asciidoc-plantuml-iuml.git (branch: master)
[14:37:29.100] INFO (asciidoctor): Skipping preprocessing of PlantUML include, because reading the referenced local file 'class_b.iuml' caused an error:
Error: ENOENT: no such file or directory, open 'class_b.iuml'
file: modules/ROOT/pages/diag-class.adoc
source: https://github.com/jay-blanc/antora-doc-asciidoc-plantuml-iuml.git (branch: master)
Site generation complete!
As shown in the log above, the repositories built to expose the issue are the following :
This follows the architecture below :
And here is the result I got after building the documentation :
As you can see, the content of the 2 classes is empty because the 2 iuml files defining them haven’t been found/loaded.
Could you please tell me what I did wrong / if what I want to do is possible ?
Thank you :)
I'm generating the docs with Antora ,
myDiagramm.puml
looks like below :and
globals.iuml
resides in the same folder asmyDiagramm.puml
, which ispartials/uml
When executing Antora, I'm getting