Veröffentlichung von Inhalten

IFS-Logo 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)
content:
  sources:
    - url: ./isyfact-standards-3.x
      branches: HEAD
      start_path: isyfact-standards-doc/src/docs/antora

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 HEAD gesetzt sein, um den lokalen, ausgecheckten Stand 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.