Can't open included iuml when running Antora

[jvmlet]

I'm generating the docs with Antora , myDiagramm.puml looks like below :

@startuml
!include globals.iuml
....

@enduml

and globals.iuml resides in the same folder as myDiagramm.puml, which is partials/uml

When executing Antora, I'm getting

Skipping preprocessing of PlantUML include, because reading the referenced local file 'globals.iuml' caused an error:
Error: ENOENT: no such file or directory, open 'globals.iuml'

[ggrossetie]

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?

[ggrossetie]

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[]
----

[jvmlet]

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

[ggrossetie]

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[].

[ggrossetie]

@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.

[yann-soubeyrand]

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?

[yann-soubeyrand]

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

[ggrossetie]

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.

[jay-blanc]

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 :

• https://github.com/jay-blanc/antora-doc-asciidoc : simple Asciidoc documentation of a component "A"
• https://github.com/jay-blanc/antora-doc-asciidoc-plantuml-simple : Asciidoc documentation with a simple standalone PlantUML diagram
• https://github.com/jay-blanc/antora-doc-asciidoc-plantuml-iuml : Asciidoc documentation with a PlantUML diagram including PlantUML fragments (iuml files defining classes)
• https://github.com/jay-blanc/antora-playbook : Playbook building the whole documentation of the 3 components

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 :)