Veröffentlichung von Inhalten

Die Online-Dokumentation besteht im Wesentlichen aus veröffentlichten Antora-Komponenten. Dieser Guide beschreibt, wie Antora-Komponenten in die Online-Dokumentation aufgenommen und aus ihr entfernt werden.

Für diesen Guide ist ein grundlegendes Verständnis des Playbooks sowie von GitHub Actions nützlich.

1. Aufnahme einer Antora-Komponente

Die Repositories der IsyFact verwenden Git LFS. Durch die fehlende Unterstützung von Git LFS seitens Antora muss nicht nur das Playbook, sondern auch der CI-Build, angepasst werden.

1.1. Anpassung des CI-Builds

Um den fehlenden LFS-Support von Antora zu kompensieren, checkt der CI-Build das Repository mithilfe der Checkout-Action manuell aus. Die Checkout-Action unterstützt Git LFS.

Die Nutzung der Checkout-Action ist in der README des Repositories dokumentiert. Besonders empfehlenswert ist die Übersicht aller Parameter sowie die Liste gängiger Beispiele.

Zur Veröffentlichung einer Antora-Komponente muss dem Workflow des CI-Builds eine neue Checkout-Action hinzugefügt werden.

Listing 1. Konfiguration der Checkout-Action für die IsyFact-Standards (Release 3.x)
jobs:
  Build:
    steps:
      - name: Checkout isyfact-standards (release/3.x)
        uses: actions/checkout@v4
        with:
          repository: IsyFact/isyfact-standards
          ref: release/3.x
          lfs: true
          sparse-checkout: isyfact-standards-doc/src/docs/antora
          path: isyfact-standards-3.x
Die Nutzung von sparse-checkout wird empfohlen, um nur die Dateien auszuchecken, die für den Build der Dokumentation benötigt werden.

1.2. Anpassung des Playbooks

Dem Playbook muss für das ausgecheckte Repository eine neue Content Source hinzugefügt werden.

1.2.1. Content Source auf Basis von Branches

Listing 2. Konfiguration einer Content Source auf Basis eines Branches
content:
  sources:
    - url: ./isyfact-standards-3.x
      branches: release/3.x
      start_path: isyfact-standards-doc/src/docs/antora
      version:
        'release/(*)': $1
        'master': '{next}.x' (1)
        '(*)': $1
1 {next} bezeichnet hierbei die nächste Hauptversion.

Hierbei muss:

  • die url aus dem Playbook auf den path aus der Checkout-Action zeigen,

  • der start_path aus dem Playbook im sparse_checkout aus der Checkout-Action enthalten sein,

  • der Parameter branches auf den ausgecheckten Git-Branch gesetzt sein, um den lokalen, ausgecheckten Stand zu verwenden,

  • der Parameter version das Mapping der Git-Referenzen auf Versionen festlegen.

Beinhaltet eine Content Source mehrere Antora-Komponenten, so ist der Parameter start_paths zu verwenden.

1.2.2. Content Source auf Basis von Tags

Listing 3. Konfiguration einer Content Source auf Basis eines Tags
content:
  sources:
    - url: ./isyfact-standards-4.0.0
      branches: HEAD
      start_path: isyfact-standards-doc/src/docs/antora
      version: '{tag}'

Hierbei muss aufgrund des Git LFS Workarounds:

  • der Parameter branches auf HEAD zeigen,

  • der Parameter version gleich dem Tag sein.

Ansonsten sind die gleichen Punkte wie bei Content Source auf Basis von Branches zu beachten.

Antora rät generell davon ab, Dokumentation aus Tags heraus zu veröffentlichen.

1.3. Playbook für lokale Entwicklung

Für die lokale Entwicklung ist es sinnvoll, ein "lokales" Playbook zu pflegen. Das lokale Playbook unterscheidet sich in folgenden Punkten vom zentralen Playbook:

  • eine Content Source beinhaltet mehrere Git Branches oder Tags,

  • es werden Feature Branches für eine Vorschau der Beiträge unterstützt,

  • die Pflege der Branches erfolgt unter Umständen lokal.

Listing 4. Konfiguration einer Content Source im lokalen Playbook
content:
  sources:
    - url: ../isyfact-standards
      branches: [HEAD, master, release/4.x, release/3.x]
      tags: [3.2.1, 4.0.0]
      start_path: isyfact-standards-doc/src/docs/antora
      version:
        'feature/(*)': $1
        'release/(*)': $1
        'master': '{next}.x' (1)
        '(*)': $1
1 {next} bezeichnet hierbei die nächste Hauptversion.

Hierbei muss:

  • die url aus dem Playbook auf den lokalen Checkout-Pfad zeigen,

  • der start_path auf die Antora-Komponenten-Konfiguration (antora.yml) verweisen,

  • der Parameter branches bzw. tags die für die Veröffentlichung bestimmten Git-Referenzen beinhalten,

  • der Parameter version das Mapping der Git-Referenzen auf Versionen festlegen.

2. Entfernung einer Antora-Komponente

Prinzipiell müssen zur Entfernung einer Antora-Komponente aus der Online-Dokumentation die Anpassungen aus Aufnahme einer Antora-Komponente rückgängig gemacht werden.

Zusätzlich ist darauf zu achten, dass durch die Entfernung einer Antora-Komponente keine ungültigen Verweise entstehen. Hierzu geben die Logs der CI-Builds (oder lokalen Builds) Aufschluss. Werden dort noch Verweise auf die entfernte Antora-Komponente als ungültig gemeldet, müssen die entsprechenden Stellen in der Dokumentation angepasst werden.