Ablageort im Repository (GitLab): Projekt4064-QS-Baukasten
Diskussionsforum (Discourse): Projekt4064-QS-Baukasten
Readme: Projekt4064-QS-Baukasten
Beschreibung des Projektes: https://bva.usercontent.opencode.de/softwaretest/qs-baukasten/
PublicCode.YML: anzeigen
OSS Compliance: anzeigen
¶ QS Baukasten Dokumentation
<div align="center">
</div>
Dieses Repository enthält das Antora-Projekt für die Dokumentation des QS-Baukastens. Dieses wird über GitLab Pages veröffentlicht und ist hier erreichbar. Einfache Änderungen können im GitLab Editor durchgeführt werden. Für aufwändigere Änderungen oder um deren
Auswirkungen direkt zu sehen, empfiehlt sich das Clonen und Bearbeiten des Repositories in einer Entwicklungsumgebung
wie Visual Studio Code oder IntelliJ. Wir freuen uns über das Interesse und die Mitarbeit von externen Personen - melden Sie sich gerne per Mail oder lesen sie im Abschnitt Mitarbeit externer Personen weiter.
¶ Ansprechpartner*innen
- Simone Mester: Simone.Mester@bva.bund.de
- Oliver Kortendick: Oliver.Kortendick@bva.bund.de
- QS-Baukasten Postfach: qs-baukasten@bva.bund.de
¶ Inhaltsverzeichnis
[TOC]
¶ Was ist Antora?
Antora ist ein Tool, mit welchem Dokumentationen erstellt und verwaltet werden können. Es verwendet eine einfache Textsyntax namens AsciiDoc, um Inhalte zu schreiben. Die fertigen Dokumente werden automatisch in eine ansprechende Webseite (html) umgewandelt.
¶ Struktur
-
`modules/ROOT/pages`
Alle Seiten des QS-Baukastens befinden sich im Ordner `modules/ROOT/pages`. Eine neue Seite muss in diesem Verzeichnis angelegt werden und die Endung `.adoc` haben. -
`modules/ROOT/images`
Hier befinden sich Bilder, die auf den Seiten des QS-Baukastens verwendet werden. Zu jeder Seite, die Bilder enthält, gibt es einen gleichnamigen Bilderordner. -
`modules/ROOT/attachments`
Hier befinden sich Word-, Excel-, PDF-Dokumente und weitere Dateien, welche z.B. zum Download angeboten werden sollen. Zu jeder Seite mit solchen Attachments, gibt es einen gleichnamigen Attachments-Ordner. -
`modules/ROOT/nav.adoc`
Die Navigation auf der linken Seite der Webseite wird von `modules/ROOT/nav.adoc`
konfiguriert. Dort werden alle Seiten in entsprechender Hierarchie aufgelistet. Die Syntax sieht wie folgt aus:
``` -
xref:Name_der_AsciiDoc_Datei.adoc[Anzeigename der Seite]
** xref:Name_einer_untergeordneten_Datei.adoc[Untergeordnete Seite]
```
Die Anzahl der Sternchen * zu Beginn legt die Tiefe in der Navigation fest und kann bis zu fünf Sterne ***** tief sein. Ein Blick in `modules/ROOT/nav.adoc`
hilft beim Verständnis. -
`antora-playbook.yml`
Das Playbook ist die zentrale Konfigurationsdatei, die die gesamte Seite steuert. Es enthält Einstellungen für den Aufbau, die Quellen und die Ausgabe der Dokumentation. -
`antora.yml`
definiert die Metadaten und Navigation einzelner Inhalte in den Modulen. -
`.gitlab-ci.yml`
Diese Datei steuert die automatische Veröffentlichung auf GitLab Pages. -
`supplemental-ui`
Wie im `antora-playbook.yml`
angegeben, verwendet dieses Projekt das Default-UI von Antora, wird jedoch von einem Supplemental UI abgeändert. Die entsprechenden Dateien befinden sich in `supplemental-ui`. Existiert eine hbs-Datei in diesem Ordner, überschreibt sie die gleichnamige hbs-Datei im Default UI. -
`build`-Ordner
Die von Antora generierten Dateien werden automatisch im ```build```-Ordner abgelegt und durch die CICD-Pipeline auf GitLab Pages veröffentlicht.
¶ Namenskonvention
- Seiten: Werden großgeschrieben und für mehrere Worte mit Bindestrichen verbunden. Umlaute (ä, ö, ü, ß) werden durch Umschreibungen dargestellt. Zum Beispiel `Beispiel-fuer-Seite.adoc`
- Bilder: Handelt es sich um ein Icon, wird an den Anfang des Namens "icon-" gehangen. So lassen sich Icons schneller von regulären Bildern unterscheiden. Zum Beispiel `icon-zusammenarbeit.png`.
Allgemein sollten mehrteilige Namen durch Binde- oder Unterstriche verbunden werden.
¶ Syntax in Antora
In `modules/ROOT/pages/Template.adoc` finden Sie eine Auswahl der Antora Syntax. Die offizielle Dokumentation von Antora bietet ebenso eine gute Übersicht über die Syntax.
¶ Mitarbeit interner Personen
¶ Editieren in GitLab
Es gibt in GitLab einen einfachen Editor sowie eine Web IDE. Der einfache Editor eignet sich nur für die Bearbeitung einer einzelnen Seite. Sobald es um mehrere Dateien geht, sollte die Web IDE verwendet werden.
¶ Einfacher Editor
¶ Bearbeiten
Mit dem einfachen Editor in GitLab lässt sich nur eine Seite auf einmal ändern. Dazu muss die Seite aufgerufen und oben rechts auf den Button <button style="background-color:#1f75cb; color:white; border-radius: .25rem">Edit</button> geklickt werden. Hier wählt man "Edit single file" aus und kann die Adoc-Datei direkt bearbeiten. Nachdem die Änderungen abgeschlossen sind, beschreibt man unten bei "Commit message", welche Änderungen man vorgenommen hat und klickt auf "Commit changes".
¶ Hinzufügen
Um eine neue Datei oder einen neuen Ordner anzulegen, navigiert man zuerst in das entsprechende Verzeichnis. Oben neben dem Pfad befindet sich ein Plus-Symbol +, über welches man die Auswahl hat eine Datei/einen Ordner anzulegen (New File bzw. New Directory) oder eine Datei hochzuladen (Upload File). Auch hier beschreibt man die Änderungen in der Commit Message und klickt auf "Commit Changes".
❗Wird eine neue Seite angelegt, die links in der Navigation auftauchen soll, ist die Anpassung von `modules/ROOT/nav.adoc`
zu beachten, wie im Abschnitt Struktur beschrieben.
¶ Löschen
Um eine Datei zu löschen, muss die Seite in GitLab geöffnet sein. Ein Klick auf den Button "Delete" oben rechts öffnet ein Dialogfenster, in welchem eine Commit Message angegeben werden sollte.
❗Damit die Navigation auf keine leere Seite zeigt, sollte die Seite aus der `modules/ROOT/nav.adoc`
entfernt werden, siehe Struktur.
¶ Web IDE
Die Web IDE in GitLab ist Visual Studio Code und erlaubt die Bearbeitung des gesamten Projekts. Um ihn zu öffnen, klickt man im Repository oben rechts auf den Button <button style="background-color:#1f75cb; color:white; border-radius: .25rem">Edit</button> und "Web IDE". Nach Öffnung sieht man auf der linken Seite das Dateiverzeichnis des Projekts. Die zu verändernde Seite wird mit einem Klick geöffnet und auf der rechten Seite wird der Asciidoc Code angezeigt, an dem man Änderungen vornehmen kann. Sind die Änderungen abgeschlossen, klickt man links auf das Symbol für "Source Control". Dort gibt man bei "Commit Message" ein, was man geändert hat und klickt auf "Commit and push to 'main'" (<- TODO: wird es wirklich main?).
<span style="color:red"><b>TODO Plugin?</b></span>
❗Beim Hinzufügen und Löschen von Seiten ist die Struktur in `modules/ROOT/nav.adoc`
zu beachten, wie im Abschnitt Struktur beschrieben.
¶ Lokale Benutzung
Man kann das Projekt lokal benutzen und editieren, ohne Antora zu installieren, jedoch kann man so nur die Seitenpreview in der IDE sehen und nicht die generierte HTML. Im Folgenden Kapitel geht es um die Nutzung mit lokaler Antora Installation.
¶ Vorausetzungen
Für die lokale Arbeit an Git Projekten, muss Git auf dem Rechner installiert sein.
Um Antora lokal auszuführen, muss eine long term support (LTS) Version
von Node.js installiert sein.
<details>
<summary>Windows</summary>
Ein Installer für Node.js kann zum Beispiel auf
der Node.js Webseite heruntergeladen werden.
Um nach der Installation zu überprüfen, ob Node.js korrekt installiert worden ist, kann man eine Powershell öffnen und
folgenden Befehl eingeben:
```
node --version
```
<!--
Bei erfolgreicher Installation wird die Versionsnummer ausgegeben.
Sollte trotz Installation ein Error erscheinen, wurde für Node eventuell keine Systemumgebungsvariable erstellt.
-->
</details>
<details>
<summary>Linux</summary>
```
apk add nodejs npm
```
oder per Packet Manager.
</details>
<details>
<summary>MacOS</summary>
Ein Installer für Node.js kann zum Beispiel auf
der Node.js Webseite heruntergeladen werden.
</details>
Für die Bearbeitung in IntelliJ oder Visual Studio Code empfiehlt sich die Installation eines Asciidoc Plugins:
¶ Klonen des Projekts
<details>
<summary>Mit HTTPS in IntelliJ</summary>
- Im Gitlab Repository oben rechts auf "Code" klicken und den HTTPS Link kopieren.
- In IntelliJ auf "Neu" und "Projekt von Version Control" klicken oder im Welcoming-Screen den entsprechenden Button finden.
- Im neuen Fenster den kopierten HTTPS Link eingeben und Speicherort auswählen.
- Auf "Klonen" klicken.
- Das Projekt sollte sich direkt öffnen.
- NPM-Pakete installieren
- Unten rechts sollte automatisch vorgeschlagen werden, die NPM-Pakete zu installieren. Dort auf "install klicken".
- Falls der vorige Schritt ausbleibt, kann man die Pakete im Terminal mit `npm i`installieren.
- Ist das AsciiDoc Plugin installiert, sollte sich beim Öffnen einer AsciiDoc Seite automatisch auch die Preview dieser öffnen. Wurde das Projekt einmal lokal gebaut, wird diese akkurater.
</details>
<details>
<summary>Visual Studio Code</summary>
GitLab bietet für VS Code eine simple Methode zum Klonen an.
-
Im Repository oben rechts auf "Code" und anschließend auf "Visual Studio Code (HTTPS)" klicken.
-
Das Projekt wird automatisch in VSC geöffnet und man wird aufgefordert einen Speicherort auszuwählen.
Ggf. muss in VSC zuvor "Trust Workspace" geklickt werden.
-
Das Projekt wird geöffnet.
-
Unten rechts sollte ein Vorschlag zur Installation des AsciiDoc Plugins erscheinen. Dieser sollte angenommen werden. Erscheint der Vorschlag nicht, klickt man im Menü links auf die Bausteine (Extensions) und kann das Plugin darüber installieren.
-
Um die NPM-Pakete zu installieren, öffnet man das Terminal mit STRG+ö oder klickt auf `View -> Terminal`. Dort gibt man `npm i` ein, um die Pakete zu installieren.
-
Öffnet man eine Seite, lässt sich die Vorschau anzeigen, indem man oben rechts auf das kleine Symbol mit der Lupe oder drückt `STRG+K V`.
</details>
¶ Editieren der Dokumentation
Die verschiedenen Seiten der Dokumentation befinden sich im Ordner `modules/ROOT/pages` und können mit Doppelklick in der Entwicklungsumgebung geöffnet werden. Bei voriger Installation des AsciiDoc Plugins, sollte automatisch links der AsciiDoc Code und rechts eine Preview der Seite angezeigt werden.
¶ Generierung mit Antora
Um die Website auf Basis der AsciiDoc Dateien zu generieren, wird im Ordner ```qsbk_antora``` (in einer Powershell oder im Terminal der Entwicklungsumgebung) folgender Befehl ausgeführt:
```
npx antora antora-playbook.yml
```
Der Zusatz ```--stacktrace``` kann dabei helfen, Probleme zu erkennen.
Sobald die Generierung abgeschlossen ist, lässt sich die Website öffnen. Am einfachsten öffnet man dazu die `index.html` im Ordner `build/site` im Browser. Bei Ausführung im Terminal der IDE sollte diese direkt im Terminal aufrufbar sein.
¶ Veröffentlichung auf GitLab
<details>
<summary>Terminal</summary>
Git kann unabhängig von Betriebssystem oder Entwicklungsumgebung im Terminal genutzt werden.
- Damit es zu keinen Konflikten kommt, ist es empfehlenswert vor der Veröffentlichung zu prüfen, ob in der Zeit der Bearbeitung neue Änderungen im Repository stattgefunden haben. Mit `git pull` werden remote Änderungen abgefragt und in den lokalen Branch gemerged.
- Fügen Sie mit `git add *` alle Dateien oder nach dem Schema `git add Beispielseite.adoc` einzelne Dateien in Git hinzu.
- Fügen Sie eine Commit Message hinzu, welche ihre Änderungen beschreibt: `git commit -m "Hier steht Ihre Beschreibung"`
- Pushen Sie Ihre Änderungen mit `git push` in das Repository.
</details>
<details>
<summary>IntelliJ</summary>
- Damit es zu keinen Konflikten kommt, ist es empfehlenswert vor der Veröffentlichung zu prüfen, ob in der Zeit der Bearbeitung neue Änderungen im Repository stattgefunden haben. Klicken Sie dafür in der Leiste oben links auf "main" und dann auf "Update Project". Wählen Sie im nächsten Fenster "merge incoming changes into current branch", um remote Änderungen in Ihre lokale Codebase einfließen zu lassen.
- Mit einem Klick links auf das zweite Symbol von oben ("Commit"), sieht man alle bearbeiteten Dateien. Wählen Sie unter "Changes" alle veränderten Dateien per Checkbox aus. Unter "Unversioned Files" finden Sie von Ihnen neu erstelle Dateien, welche Sie noch nicht zu Git hinzugefügt haben. Wählen Sie auch hier die gewünschten Dateien aus.
- Im Textfeld darunter wird die Commit Message angegeben, in welcher Sie ihre Änderungen beschreiben können.
- Sind Sie bereit ins Repository zu pushen, klicken Sie auf den Button "Commit and Push..."
- Ihr Code wird auf mögliche Fehler analysiert und ggf. von IntelliJ angezeigt. Beurteilen Sie selbst, ob es sich um tatsächliche Fehler handelt oder die Warnungen ignoriert werden können.
- In einem neuen Fenster können Sie die zu veröffentlichen Dateien noch einmal sehne. Klicken Sie abschließend auf den Button "Push".
</details>
<details>
<summary>Visual Studio Code</summary>
- Damit es zu keinen Konflikten kommt, ist es empfehlenswert vor der Veröffentlichung zu prüfen, ob in der Zeit der Bearbeitung neue Änderungen im Repository stattgefunden haben. Klicken Sie dafür links auf das dritte Symbol von oben ("Source Control"), unter der Lupe. Im unteren Teil dieser Ansicht sehen Sie die Änderungshistorie des Repositorys. Dort befindet sich ein Symbol mit einem nach unten zeigenden Pfeil, welcher "Pull" heißt, wenn man mit der Maus drüber hovert. Klicken Sie dieses Symbol, um ggf. remote Änderungen in Ihre lokale Codebase einfließen zu lassen.
- In der linken Ansicht sollten Sie unter "Changes" die von Ihnen bearbeiteten Dateien sehen. Um alle Dateien zu Git hinzuzufügen, hovern Sie mit der Maus über Changes und klicken Sie das Plus Symbol. Alternativ können sie einzelne Dateien auf die gleiche Weise hinzufügen.
- Oben links können Sie eine Commit Message eintragen, welche Ihre Änderungen beschreibt.
- Klicken Sie rechts vom Button "Commit" auf den Pfeil und wählen Sie "Commit & Push", um Ihre Änderungen in das Repository zu pushen.
</details>
¶ Mitarbeit externer Personen
Wir freuen uns, wenn Sie am QS-Baukasten mitwirken möchten! Kontaktieren Sie uns gerne, um ein weiteres Vorgehen zu besprechen. Möchten Sie Änderungen und Erweiterungen selbst in die Hand nehmen, halten Sie sich bitte an den folgenden Abschnitt.
Die Bearbeitung am QS-Baukasten findet bei externer Mitarbeit nicht direkt in diesem Repository auf dem Main-Branch statt. Stattdessen wird das Repository geforkt, nach Abschluss der Änderungen geprüft und bei Zustimmung in den QS-Baukasten gemerged.
- Fork
Ein Fork ist eine Kopie eines bestehenden Repositorys und wird in Ihrem eigenen Bereich erstellt. Oben rechts im QS-Baukasten Repository finden Sie den Button "Fork". Alternativ hier. - Klonen Sie den Fork, um ihn lokal zu bearbeiten oder führen Sie die Änderungen auf GitLab direkt durch.
- Wenn Sie alle Änderungen vorgenommen und in Ihren Fork gepusht haben, können Sie einen Merge Request in das Repository des QS-Baukastens stellen.
Klicken Sie dazu in ihrem Fork auf der linken Seite auf "Merge requests" und anschließend auf den Button "New merge request". Wählen Sie bei "Source Branch" den Branch in ihrem Fork und bei "Target Branch" den Main-Branch des originalen QS-Baukasten Repositorys aus und klicken Sie auf "Compare branches and continue".
Wählen Sie im nächsten Schritt bei "Titel" und "Description" Beschreibungen, die Ihre Änderungen gut beschreiben (<span style="color:red"><b>TODO:</b></span> Assignee auswählen?) und klicken Sie auf "Create merge request". - Ihre Änderungen werden anschließend intern geprüft und bei Genehmigung in den QS-Baukasten aufgenommen.
¶ Lizenz
Dieses Projekt steht unter der Creative Commons Namensnennung – Weitergabe unter gleichen Bedingungen 3.0 Deutschland (CC BY-SA 3.0 DE) Lizenz.
Das bedeutet:
- Sie dürfen das Werk vervielfältigen, verbreiten und öffentlich zugänglich machen.
- Sie dürfen das Werk remixen, verändern und darauf aufbauen.
Bedingungen:
- Namensnennung: Sie müssen den Urheber angemessen nennen, einen Link zur Lizenz beifügen und angeben, ob Änderungen vorgenommen wurden. Diese Angaben dürfen nicht so gemacht werden, dass der Eindruck entsteht, der Urheber unterstütze Ihre Nutzung.
- Weitergabe unter gleichen Bedingungen: Wenn Sie das Material bearbeiten, transformieren oder darauf aufbauen, müssen Sie Ihre Beiträge unter derselben Lizenz wie das Original verbreiten.
Weitere Informationen finden Sie unter:
https://creativecommons.org/licenses/by-sa/3.0/de/