search

admin-shell-io / aas-specs

Repository of the Asset Administration Shell Specification IDTA-01001 - Metamodel
https://admin-shell-io.github.io/aas-specs-antora/index/home/index.html
Creative Commons Attribution 4.0 International
47 stars 26 forks source link

[BUG] 'nav.adoc' uses incomplete paths | Build for antora fails #335

Closed monsieuremre closed 6 months ago

monsieuremre commented 6 months ago

Problem A separate nav.adoc file is being used for the asciidoc type documentation. This is normally not a problem but the paths in the navigation specification are incomplete. Building for antora will return errors and won't complete as desired. Only the titles and description in the navigation index page will show. You can have a look at it at for yourself at https://rwth-iat.github.io/aas-specs-antora/.

Marked with Part 1 is our own file structure. Marked with the full specification title is what happens when this repository used a source.

On a separate issue, logos and stylistic elements are better handled using a dedicated UI package, as we do here. So the logo etc. are superfluous to include here in individual pages.

Build process for antora will return these errors:

[11:05:56.183] ERROR (asciidoctor): target of include not found: ./IDTA-01001_Constraints.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:24
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.186] ERROR (asciidoctor): level 0 sections can only be used when doctype is book
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:27
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.188] ERROR (asciidoctor): target of image not found: ../../idta-logo.png
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.195] ERROR (asciidoctor): target of include not found: ./IDTA-01001_Preamble.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:35
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.196] ERROR (asciidoctor): target of include not found: ./IDTA-01001_General.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:37
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.197] ERROR (asciidoctor): target of include not found: ./IDTA-01001.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:39
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.197] ERROR (asciidoctor): target of include not found: ./IDTA-01001_DataSpecifications.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:41
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.198] ERROR (asciidoctor): target of include not found: ./IDTA-01001_Mappings.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:43
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.199] ERROR (asciidoctor): target of include not found: ./IDTA-01001_SummaryOutlook.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:45
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.199] ERROR (asciidoctor): target of include not found: ./Annex/IDTA-01001_ConceptsAAS.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:49
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.200] ERROR (asciidoctor): target of include not found: ./Annex/IDTA-01001_Requirements.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:51
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.206] ERROR (asciidoctor): target of include not found: ./Annex/IDTA-01001_UsageMetamodel.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:59
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.207] ERROR (asciidoctor): target of include not found: ./Annex/IDTA-01001_MetamodelWithInheritance.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:61
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)
[11:05:56.207] ERROR (asciidoctor): target of include not found: ./Annex/IDTA-01001_ChangeLog.adoc
    file: documentation/IDTA-01001/modules/ROOT/nav.adoc:63
    source: https://github.com/admin-shell-io/aas-specs (branch: BiBo/IDTA-01001-3-1_working | start path: documentation/IDTA-01001)

Where The branch BiBo/IDTA-01001-3-1_working.

Additional context You can see the full specifcation for in the antora playbook here.

The relevant part is the following:

    - url:  https://github.com/admin-shell-io/aas-specs
      branches: BiBo/IDTA-01001-3-1_working
      start-paths: documentation/IDTA-01001

Solution A solution would be fixing the paths to match the real paths. ./IDTA-01001_General.adoc should be ./pages/IDTA-01001_General.adoc or whatever the real path is. Recommended is importing our implemented functional file structure directly. We can implement the nav page structure in our oprhan branch if desired, and that can be later imported here.

BirgitBoss commented 6 months ago

Yes, we need an additional antora-ui repo. W.r.t. nav.adoc others are using xref, e.g.

.Specification
xref:index.adoc[Introduction]

So I assume changing of "include::" to "xref:" should also fix the problem?

BirgitBoss commented 6 months ago

Is there a reason you have chosen MPL-2.0 license for https://github.com/rwth-iat/aas-specs-antora-ui? We need to discuss a suitable license.

BirgitBoss commented 6 months ago

Since we sometimes have a deep chapter hierarchy a solution like in https://eclipse-esmf.github.io/samm-specification/snapshot/characteristics.html (left only main chapters, on the right the sub-chapters of the main chapter) migth also be helpful. The overall document series can be get when clicking on the top left icon and name: https://eclipse-esmf.github.io/esmf-documentation/index.html

monsieuremre commented 6 months ago

Is there a reason you have chosen MPL-2.0 license for https://github.com/rwth-iat/aas-specs-antora-ui? We need to discuss a suitable license.

Our UI is based on the Antora Default UI. It is like a fork. The original repository is licensed under the Mozilla Public Licese, which is a copyleft license. We have no choice but to use the same license when we do modifications or additions to MPL code, otherwise it would violate the terms of the license.

The overall document series can be get when clicking on the top left icon and name: https://eclipse-esmf.github.io/esmf-documentation/index.html

This is also to be handled in the UI.

Since we sometimes have a deep chapter hierarchy a solution like in https://eclipse-esmf.github.io/samm-specification/snapshot/characteristics.html (left only main chapters, on the right the sub-chapters of the main chapter) migth also be helpful.

The ones on the left are what is declared in the source repository with a nav.adoc file, as you do here. They would appear left. Right side is automatically generated from the sections and chapters of the selected page. This is handled in the UI, no effort needed here. So fixing the nav.adoc will result in this look exactly.

So I assume changing of "include::" to "xref:" should also fix the problem?

I am not sure but I would assume so. This might result in differences in appearance or functionality. I can check both possibilities and create a pull request with a functional and appropriate solution if you would like that.

If you would like to test out yourself, you can use the instructions in our repository locally (fast and recommended) or do the changes here and wait until the website gets regenerated automatically (not recommended, involves waiting).

BirgitBoss commented 6 months ago

The ones on the left are what is declared in the source repository with a nav.adoc file, as you do here. They would appear left. Right side is automatically generated from the sections and chapters of the selected page. This is handled in the UI, no effort needed here. So fixing the nav.adoc will result in this look exactly.

https://rwth-iat.github.io/aas-specs-antora/index/dev/index.html is not yet how it should finally look like. Please compare to the documentation of asciidoc documentation itself: https://docs.asciidoctor.org/

Before changing this directory we need to be sure on what exactly needs to be changed.

monsieuremre commented 6 months ago

The recent changes don't fix the problem, I have redeployed the website to demonstrate, you can check. But I have tested a working solution.

:doctype: book
:toc: left
:toc-title: Part 1: Metamodel
:imagesdir: ./images/

include::.pages/IDTA-01001_Constraints.adoc[]
include::../Shared/pages/IDTA-01xxx_TermsDefinitionsAbbreviations.adoc[]

* xref:IDTA-01001_Preamble.adoc[Preamble]

* xref:IDTA-01001_General.adoc[General]

* xref:IDTA-01001.adoc[Metamodel]

* xref:IDTA-01001_DataSpecifications.adoc[Data Specifications]

* xref:IDTA-01001_GrammarSemanticIdsMetamodel.adoc[Grammar Semantic ID's]

* xref:IDTA-01001_Mappings.adoc[Mappings]

* xref:IDTA-01001_SummaryOutlook.adoc[Summary Outlook]

* xref:Annex/IDTA-01001_ConceptsAAS.adoc[Annex - Concepts]

* xref:Annex/IDTA-01001_Requirements.adoc[Annex - Requirements]

* xref:Annex/IDTA-01001_ValueOnlySerializationExample.adoc[Annex - Example]

// * xref:./Shared/pages/Annex/IDTA-01xxx_BackusNaurForm.adoc[Annex - BackusNaurForm]

// * xref:./Shared/pages/Annex/IDTA-01xxx_UMLTemplates.adoc[Annex - UML Templates]

// * xref:./Shared/pages/Annex/IDTA-01xxx_UML.adoc[Annex - UML]

* xref:Annex/IDTA-01001_HandlingConstraints.adoc[Annex - Handling Constraints]

* xref:Annex/IDTA-01001_UsageMetamodel.adoc[Annex - Usage Metamodel]

* xref:Annex/IDTA-01001_MetamodelWithInheritance.adoc[Annex - Metamodel with Inheritance]

* xref:Annex/IDTA-01001_ChangeLog.adoc[Annex - Changelog]

//* xref:../Shared/pages/Annex/IDTA-01xxx_Bibliography.adoc[Bibliography]

the nav file should like this.

The file IDTA-01001.adoc should begin directly without declaring properties. So the lines

:toc: left
:toclevels: 4
:toc-title: Specification of the Asset Administration Shell. Part 1: Metamodel
:sectlinks:
:sectnums:
:nofooter:

should be deleted completely. This information is declared in the nav file. Shared annexes cannot be accessed in this manner in my testing, nor should they be. This is better handled by having a shared annexes branch and the xrefs will link to that source. Otherwise having these in the main nav on the main page is always an option too. If you still would like to keep this way of accessing, then the shared folder should move under pages. Then it can be accessed.

BirgitBoss commented 6 months ago

Done

BirgitBoss commented 6 months ago

Please add PR and do not describe in issues what needs to be done