Veröffentlichung von Inhalten

Diese Seite ist ein Teil der IsyFact-Standards. Alle Inhalte der Seite, insbesondere Texte und Grafiken, sind urheberrechtlich geschützt. Alle urheberrechtlichen Nutzungs- und Verwertungsrechte liegen beim Bundesverwaltungsamt.

Creative Commons Namensnennung Die Nutzung ist unter den Lizenzbedingungen der Creative Commons Namensnennung 4.0 International gestattet.

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.

Listing 2. Konfiguration der Content Source für die IsyFact-Standards (Release 3.x) in 'antora-playbook.yml'

content:
  sources:
    - url: ./isyfact-standards-3.x
      branches: release/3.x
      tags: [3.2.1]
      start_path: isyfact-standards-doc/src/docs/antora
      version:
        'release/(*)': $1
        'master': '5.x'
        '(*)': $1

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 tag key selektiert eine Reihe von Git-Tags.
das Version-Mapping legt den version key für eine Antora-Komponente fest.

Beinhaltet ein Content-Source mehrere Antora Komponenten, so ist der start_paths key zu verwenden.

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.

2.1. Playbook für lokale Entwicklung

Für die lokale Entwicklung ist es sinnvoll ein weiteres Playbook antora-playbook-local.yml 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 3. Konfiguration der Content Source für die IsyFact-Standards (Release 3.x) in 'antora-playbook-local.yml'

content:
  sources:
    - url: ../isyfact-standards
      branches: master, HEAD, release/4*, release/3.x*, release/3.2.1
      tags: [4.0.0]
      start_path: isyfact-standards-doc/src/docs/antora
      version:
        'feature/(*)': $1
        'release/(*)': $1
        'master': '5.x'
        '(*)': $1

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 die für die Veröffentlichung bestimmten Git-Branches beinhalten.
der tag key selektiert eine Reihe von Git-Tags.
das Version-Mapping legt den version key für eine Antora-Komponente fest.

Beinhaltet ein Content-Source mehrere Antora Komponenten, so ist der start_paths key zu verwenden.

Antora rät generell davon ab, Dokumentation aus Tags zu ziehen, siehe Content Keys - Tags

Das lokale checkout der Dokumentation mit Git LFS kann über eine Antora Erweiterung realisiert werden, siehe Antora extension Use Cases