Modul Dokumentation - Template Generator

Bitte bei der Neuerstellung bzw. beim bearbeiten einer evtl. älteren Asciidoc erstellten Modul Dokumentation immer mittels des Modul Template Generators eine Modul Dokumentation zu erstellen/Updaten und bestehender Content von alt ⇒ neu portieren.

Dies ist in der Regel kein grosser Aufwand bei Modulen, und nur mit geringen Zeitaufwand möglich und sollte deshalb immer auf <<section-generation-update,Notwenigkeit> geprüft werden.

Nur so kann ein qualitativ guter Standard bei allen Dokumentationen gehalten werden.

Im der Regel sollte dies bei einen Modul Version Update geschehen.

Beschreibung

Beim Modul Dokumentation - Modul Template Generator handelt es sich um ein Tool, das es uns erleichtert, out of the box initial eine asciidoc Modul Dokumentation nach den TechDivision Richtlinien zu generieren.

Wann brauche ich den Modul Template Generator:

Eine Modul Dokumentation ist noch nicht vorhanden
Eine bestehende Modul Dokumentation, aber noch im alten Format befindliche Modul Dokumentation muss auf den neusten Asciidoc Stand gebracht werden

Struktur

📒 modul-adoc-generator (1)
    📂 TemplateAsciiDocs (2)
        📂 {foldername} (3)
            📂 modules (4)
                📂 ROOT (5)
                    📂 images (6)
                        📄 config-category-imagename.png
                        📄 config-modul-imagename.png
                        📄 config-store-imagename.png
                        📄 config-storeview-imagename.png
                        📄 manual-imagename.png
                        📄 testcase-imagename.png
                    📂 pages (7)
                        📄 _contributers.adoc (8)
                        📄 _description-functions.adoc (9)
                        📄 _description.adoc (10)
                        📄 _jira.adoc (11)
                        📄 _overview.adoc (12)
                        📄 _tags.adoc (13)
                        📄 changelog.adoc (14)
                        📄 config-category.adoc (15)
                        📄 config-modul.adoc (16)
                        📄 config-store.adoc (17)
                        📄 config-storeview.adoc (18)
                        📄 config.adoc (19)
                        📄 faq.adoc (20)
                        📄 index.adoc (21)
                        📄 installation.adoc(22)
                        📄 manual.adoc(23)
                        📄 references.adoc(24)
                        📄 requirements.adoc(25)
                        📄 servicedescription.adoc(26)
                        📂 sos(27)
                            📄 _functions.adoc(28)
                            📄 _glossary.adoc(29)
                            📄 _misc.adoc(30)
                            📄 _tech-info.adoc (31)
                        📄 test.adoc (32)
                        📄 testcases.adoc (33)
                    📄 nav.adoc (34)
        📄 .gitignore
        📄 antora.yml (35)
        📄 config_pdf.adoc (36)
        📄 documentation-pdf.adoc (37)
        📄 README.md (38)
        📄 servicedescription-pdf.adoc (39)
    📄 asciidoc-icon.png (40)
    📄 README.md
📄 .gitignore
📄 _dump.sh (41)
📄 _functions.sh (42)
📄 _params.sh (43)
📄 _steps.sh (44)
📄 install.sh (45)
📄 README.md

1	Main Folder des Modul Template Generators
2	Hierin befindet sich der Template Ordner `{foldername}` und das Modul Icon
3	Dummy Ordner mit allen Dokumentationsdateien und Platzhaltern zum späteren generieren der Dokumentation
4	Antora Dokumentation Modul Ordner
5	Antora Main Modul `ROOT` Ordner. Alle Dokumentation relevanten Module werden hier abgelegt
6	Dokumentation `images` Ordner. Hier werden alle Bilder abgelegt
7	Im `pages` Ordner werden alle `asciidoc` Dateien abgelegt
8	Hier werden alle an dieser Dokumentation beteiligten Personen gelistet.
9	Zusätzlich zur Modul Bescheibung werden hier die speziellen Modulmerkmale gelistet
10	Modul Bescheibung
11	Kleine Hilfe: Auto generierte Jira Ticket Kommentar Texte für das Review/Testing
12	Zusätzlicher Textblock. Dieser ist in der Regel in der Regel in der Leistungsbeschreibung zu sehen. Kann aber auch beliebig eingesetzt werden.
13	In Asciidoc können auch Tags als Snippets verwendet werden. Allgemeingültige Snippets werden hier plaziert und dann entsprechend referenziert, ansonnsten kann man aus jeden Dokument heraus auch Tags definieren, fals notwendig
14	Spiegelt die Gitlab Repository Tag History wieder
15	Falls notwendig, hier alle Modul Kategorie relevanten Optionen eintragen (falls nicht benötigt, kann diese Datei auch entfernt werden. Darauf achten, dass dann auch alle diesbezüglichen Links und Referenzierungen entfernt werden)
16	Modul relevante Optionen
17	Falls notwendig, hier alle Modul Store relevanten Optionen eintragen (falls nicht benötigt, kann diese Datei auch entfernt werden. Darauf achten, dass dann auch alle diesbezüglichen Links und Referenzierungen entfernt werden)
18	Falls notwendig, hier alle Modul Storeview relevanten Optionen eintragen (falls nicht benötigt, kann diese Datei auch entfernt werden. Darauf achten, dass dann auch alle diesbezüglichen Links und Referenzierungen entfernt werden)
19	WIP: Hier werden alle zu dieser Dokumentation benötigten, mehrfach verwendeten Asciidoc Attribute abgelegt und können mit `{attributename}` referenziert werden. Evtl. werden diese in die `antora.yml` ausgelagert, ist aber noch in Testing, da es bei der PDF Generierung Probleme gibt
20	Optional: Modul relevante FAQs
21	Initiale Startseite der Dokumentation
22	Modul Installationsanleitung
23	Required: Manual (step by Step): Anleitung zum Initialen einrichten des Moduls nach der Erstinstallation
24	Optional: Modul relevante Linksammlung zum Thema
25	Modul relevante System Requirenments
26	Ordner aller Leistungsbeschreibung relevanten nformationen
27	Beschreibung der Leistungsbeschreibung
28	Leistungsbeschreibung: Auflistung aller Modul relevanten Funktionen
29	Leistungsbeschreibung: Glossary, kann aber auch in die Dokumentation mit eingebracht werden
30	Leistungsbeschreibung: Nutzungs- und Tech. Bedingungen
31	Leistungsbeschreibung: Generelle Modul Informationen (Modulmname, Hersteller, Lizenzart, …)
32	Nur eine testdatei:)
33	Optional: Modul Anwendungsbeispiel. Ist zwar optional, sollte aber immer zumindest 1 Anwendungsbeispiel vorhanden sein
34	Modul Navigationsdatei. Diese beinhaltet die Navigation der Dokumentation
35	Required\|WIP: Wichtigste Datei. Diese beinhaltet sowohl alle Antora Optionen, als auch Modul Attribute
36	Required: PDF relevante Antora Attribute
37	Modul PDF Version. Um eine PDF zu generieren, muss diese am Ende des Dateinamens immer `-pdf.adoc` beinhalten, damit eine PDF generiert wird
38	WIP: Asciidoc Modul Readme
39	Leistungsbeschreibung PDF Version. Um eine PDF zu generieren, muss diese am Ende des Dateinamens immer `-pdf.adoc` beinhalten, damit eine PDF generiert wird
40	Dieses Icon beim initialen einchecken ins Gitlab als Modul Icon unter `Repository Settings General [Project avatar]` einsetzen
41	Beinhaltet die Ausgabe diverser Infos während der Modul Dokumentationsgenerierung
42	Installationsrelevante Helper Functions
43	Vordefinierte Installationsoptionen. können teilweise beim Installieren als `-option` Installationsoptionen überschrieben werden
44	Output der Generierung Steps
45	Initiale Install Generierungsdatei

Commands

Tabelle 1. Der Befehl ***cadoc*** beschreibt hier exemplarisch einen Aliasnamen für den Pfad zur `install.sh` Datei des **Modul Template Generator**. Dieser Alias kann aber auch beim initialen Aufsetzen des **Modul Template Generators** nach eigenen Angaben definiert werden
Command	Option	Beschreibung
cadoc	-h\|--help	Hilfe und Beschreibung zu allen existierenden Command Optionen
cadoc	-c\|--create-adoc-dummy	Erstellen der Dummy Modul Dokumentation im Ordner repos-modules
cadoc	-title\|--adoc-modul-title	Angabe des Modul Titels. Erscheint als Dokumentationstitel (Gross/Kleinschreibung)
cadoc	-name\|--repo-modul-name	Angabe des zukünftigen Repository Namen. Der Modul Ordnername sollte den gleichen Namen wie das Repository haben
cadoc	-version\|--repo-modul-version	Branch Version des Modul Repositories. Immer beginnend mit <v*> (z.B. v1.0)
cadoc	-namespace\|--repo-namespace	Angabe des Repository Namespaces. Als Default ist eingestellt: <techdivision>
cadoc	-phpv\|--php-version	Angabe der benötigten Magento PHP Version. Als Default ist eingestellt: <7.3>
cadoc	-magv\|--magento-version	Angabe der benötigten Magento Version. Als Default ist eingestellt: <2.4>
cadoc	-crepo\|--create-git-repo	Bei Angabe von [-crepo\|--create-git-repo] wird ein locales Git Repository im Modul Dokumentation Ordner erstellt. Die Angabe des Wertes <1> is hier optional. Als Default ist eingestellt: <0>.
cadoc	-params\|--install-params	Bei dieser Option werden die voreingestellten Optionswerte ausgegeben
cadoc	-steps\|--install-steps	Bei dieser Option werden die Installationsschritte ausgegeben

Update von Attributs

Ein Update bzw. anpassen der vordefinierten Attributs kann auf 2 Arten erfolgen:

Update des Repositories auf den neusten Adoc/Modul Template Stand via CLI Command Options
Update der Standard Attribut Werte in der Datei _params.sh des Modul Template Generator

Folgende Attribute machen Sinn verändert zu werden:

Attribut Default Beschreibung

Attribut	Default	Beschreibung
NAME	my-repository-name	Hier handelt es sich bei einen Update um den Repository Namen der Modul Dokumentation
TITLE	My Modul Title	Der Dokumentationstitel besteht bei einen Modul Dokumentation Update und wird hier in der Regel übernommen und eingetragen
NAMESPACE	techdivision	Beschreibt den Modul Dokumentation GItlab Namespace. Sollte aber in der Regel aber immer `techdivision` sein
PHP_VERSION	7.3	Benötigte PHP Version der benutzten Magento Instanz
CREATE_REPO	0	Beim initialen neu erstellen eines Modul Dokumentation Templates muss dieses Attribut gesetzt sein mit `-crepo`, um das Modul Dokumentation Repository zu erstellen Bei einen Update Template muss dieses Attribut nicht gesetzt sein, da ja schon ein Repository existiert
MAGENTO_VERSION	4.2	Benötigte Magento Version

NAME

my-repository-name

Hier handelt es sich bei einen Update um den Repository Namen der Modul Dokumentation

TITLE

My Modul Title

Der Dokumentationstitel besteht bei einen Modul Dokumentation Update und wird hier in der Regel übernommen und eingetragen

NAMESPACE

techdivision

Beschreibt den Modul Dokumentation GItlab Namespace. Sollte aber in der Regel aber immer techdivision sein

PHP_VERSION

7.3

Benötigte PHP Version der benutzten Magento Instanz

CREATE_REPO

Beim initialen neu erstellen eines Modul Dokumentation Templates muss dieses Attribut gesetzt sein mit -crepo, um das Modul Dokumentation Repository zu erstellen
Bei einen Update Template muss dieses Attribut nicht gesetzt sein, da ja schon ein Repository existiert

MAGENTO_VERSION

4.2

Benötigte Magento Version

Installation Steps des Modul Template Generators

Der Modul Template Generator ist so konzipiert, dass er bei Mac im Users Ordner abgelegt wird und dann als Alias von überall aufgerufen werden kann.

Folgende Schritte sind notwendig dazu:

Öffnen des Bashtools ihrer Wahl (Terminal|ITerm2| …)

Navigieren zum lokalen Mac Users Ordner

cd /Users/<myUsername>

Navigieren zum Speicherort ihrer Bashscripte bzw. erstellen sie ein Ordner, in dem Sie alle ihre Bashscripts sammeln. In unseren Fall erstellen

wir exemplarisch mal den Ordner bash-scripts

mkdir bash-scripts

Navigieren Sie nun in den Ordner bash-scripts mit

cd bash-scripts

Erstellen Sie nun einen Clone des Modul Template Generators

git clone ssh://git@gitlab.met.tdintern.de:10022/met/devdocs/antora/modul-adoc-generator.git

Öffnen der lokalen bash Datei ihrer Wahl ( ~/.bash_profile | ~/.zshrc | … ), in der Sie ihre Aliase erstellen wollen via (Terminal|ITerm2| …), oder einen Editor ihrer Wahl
Eintrag eines Alias für den Modul Template Generator

# modul-adoc-generator
alias modul-adoc-generator="/Users/<myUsername>/bash-scripts/modul-adoc-generator/install.sh"
alias cadoc=modul-adoc-generator

Datei mit den beinhaltenden Aliases speichern

source /Users/<myUsername>/< ~/.bash_profile> (1)

1	Dies kann die Datei ihrer Wahl sein ( `~/.bash_profile` \| `~/.zshrc` \| `…` )

Generation einer neuen Modul Dokumentation

Um eine neue Modul Dokumentation zu erstellen, sollten sie sich im aktuellen repos-modules Ordner ihres lokalen Workspace Antora build befinden, denn von hier aus werden die Dokumentationen via Playbook referenziert und dann zu HTML konvertiert.

Navigieren Sie in den Ordner mit all ihren Modul Dokumentation Repositories

cd /Volumes/workspace/<myworkspace>/<my-antora-build-location>/repos-modules

Example Modul Command zum ertellten einer neuen Modul Dokumentation inkl. initialen lokalen Modul Repository

cadoc -c -name "<modulname>" -title "Modul Title" -v "1.0" -phpv "7.3" -magv "2.4" -crepo

bzw. falls die voreingestellten Attribute übereinstimmen mit den Requirenments, diese einfach weglassen

cadoc -c -name "<modulname>" -title "Modul Title" -crepo

Generation einer Modul Dokumentation bei einen Update auf den neuen Asciidoc Standard

Warum ein Update der Adoc Dateien?

Um Headline Errors bei der PDF Generierung zu verhindern, Antora Adoc gibt hier eine bestimmte Implementierung vor
Reorganisation der korrekten Headline Anordnung in richtige Reihenfolge
Modulweit Antora Attribute überschreiben und bereitstellen ( Update von Antora auf v2.3)
Fix der Headline Anordnung bei PDF Generierung
Antora Modulweite Überschreibung der Block Titel
Automatisches setzen der Host Url mit globalen Attribute, um generischer zu werden
Anpassung an das neue Layout bei Tabellen inkl. automatiches Formatieren von Zelleninhalten soweit möglich
Einbau von Image Zoom als Bildvergrosserung anstatt dem öffnen eines neuen Tabs (Fehlerträchtig wenn url fehlerhaft)
Entschlackung der config.adoc. Auslagerung von globalen Antora Einstellungen in das build Playbook
Installation Text und viele andere Text ein wenig optimiert