Ein neues Dokumentationsmodul erstellen

Francois Andrieu, Fedora-Dokumentationsteam, 28. April 2023

Dieser Abschnitt beschreibt, wie Sie eine komplett neue Dokumentation erstellen, die ein neues Thema umfassend abdeckt. Diese Dokumentation erstreckt sich über mehrere Seiten und ist üblicherweise mit der Erstellung eines neuen, dedizierten Repositorys verbunden. Eine lokale Arbeitsumgebung eignet sich hierfür am besten. Alternativ können Sie auch die Web-IDE verschiedener Git-Plattformen nutzen.

Bevor Sie beginnen, überprüfen Sie bitte alle Voraussetzungen.

Konfiguration des Dokumentations-Repositorys

Sie können zwar ein neues Repository erstellen oder ein bestehendes verwenden, wir empfehlen jedoch, mit dem bereitgestellten Vorlagen-Repository zu beginnen, wenn Sie mit Antora nicht vertraut sind.

Erstellen Sie ein neues Repository für die neue Dokumentation oder bitten Sie jemanden, eines für Sie anzulegen. Sie können dieses Repository an einem beliebigen Ort hosten, wir empfehlen jedoch die Verwendung von GitLab, da Sie dort Fedora-Gruppen nutzen können, um den Schreibzugriff auf das Repository zu steuern. Je nach Thema kann es jedoch sinnvoll sein, es im Namensraum Fedora Docs zu hosten.

Auf GitLab können Sie New project > Create from template > Group wählen und Documentation Template in der Liste auswählen.

Wenn Sie GitLab nicht verwenden, klonen Sie das Vorlagen-Repository manuell und kopieren Sie den Inhalt in Ihr neues Repository.

Beispiel einer einfachen Dokumentationsrepository-Struktur

📄 antora.yml
📄 site.yml
📂 modules
  📂 ROOT
    📄 nav.adoc
    📂 pages
      📄 index.adoc
      📄 another-page.adoc

Bearbeiten Sie die Konfigurationsdatei antora.yml im Wurzelverzeichnis des neuen Repositorys. Die Datei enthält Kommentare, die darauf hinweisen, welche Teile Sie ändern müssen. Ändern Sie mindestens die Werte für name und title.

Der Wert name definiert die endgültige URL Ihrer Dokumentation. Beispiel: docs.fedoraproject.org/en-US/<name>/

Bearbeiten Sie außerdem die Konfigurationsdatei site.yml. Beachten Sie, dass diese Datei nur beim Erstellen einer lokalen Vorschau Ihrer Inhalte verwendet wird – auf der Website wird sie durch die websiteweite site.yml-Konfiguration überschrieben. Die einzigen Direktiven, die Sie in dieser Datei bearbeiten müssen, sind title und start_page.

Die Erstkonfiguration ist nun abgeschlossen. Sie können diese Änderungen in das neu erstellte Repository übertragen (oder einen Pull Request erstellen, falls Sie nicht über die erforderlichen Berechtigungen verfügen) und mit dem Schreiben der eigentlichen Dokumentation beginnen.

Dokumentation schreiben

Einige nützliche Dokumentationslinks:

Besteht Ihre Dokumentation aus mehreren Seiten, können Sie diese in der Datei nav.adoc auflisten. Diese Datei wird dann verwendet, um das Navigationsmenü auf der linken Seite von docs.fp-o zu erstellen.

Während des Schreibens können Sie mit der lokalen Vorschau das resultierende Dokument überprüfen.

Ein neues Dokumentationsmodul veröffentlichen

Sobald das Repository eingerichtet und erste Inhalte hinzugefügt wurden, kann es veröffentlicht werden.

Alle auf docs.fp-o veröffentlichten Dokumentationsmodule sind im Haupt-Antora-Playbook aufgeführt.

Um ein neues Dokumentationsmodul hinzuzufügen, müssen Sie dessen Repository zur Liste content.sources hinzufügen:

content:
  sources:
  - url: https://gitlab.com/pfad/zum/neuen/repository.git
    branches: main (1)
    start_path: docs (2)

1 Der Standardzweig ist master. Falls Ihr Repository einen anderen Namen verwendet (z.B. main), müssen Sie diesen hier angeben. <.> Diese Einstellung ist optional. Befinden sich die Dokumentationsdateien in einem Unterverzeichnis Ihres Repositorys (z.B. /docs/), müssen Sie hier den relativen Pfad ohne führende oder nachfolgende Schrägstriche angeben. Befinden sie sich im Wurzelverzeichnis, wie auf dieser Seite beschrieben, können Sie diesen Parameter weglassen.

Sie können entweder einen Merge Request mit diesen Änderungen erstellen, oder, falls Sie sich mit der Bearbeitung dieser Datei nicht wohlfühlen, ein Ticket im Repository der Fedora-Dokumentationswebsite erstellen, und das Dokumentationsteam wird sich um diesen Teil für Sie kümmern.

Sollten Sie nach 5 Tagen keine Aktualisierung zu Ihrem Merge Request oder Ticket erhalten, wenden Sie sich bitte an das Dokumentationsteam.

Want to help? Learn how to contribute to Fedora Docs ›