Local Antora Installer

Beschreibung

Der Antora Installer ist ein Teil des TechDivision Antora “build” und und bietet die Möglichkeit, nach Installation aller Requirenments, eine komplette Antora Entwickler und Test Instance local bereitzustellen.

Der Installer ist so aufgebaut, dass für jede vorhandene Dokumentation je ein Playbook (MyPlaybook.yml) im Build ROOT vorliegt (bzw. hinzugefügt werden kann) und dazu entsprechend abgerufen werden kann.

Es wird beim Antora Installer alles automatisch angelegt, von den localen valet.sh Links bis hin zu den benötigten development Ordnern.

Struktur

build Antora Struktur

Der build Ordner beinhaltet alle relevanten Files für Antora inklusive des lokalen Antora Installer

📒 build (1)
    📂 bin (2)
        📂assets (3)
            📄 gen-pdf.php
            📂 modules (4)
                📄 ui-bundle.zip
            📂 pacemaker (4)
            📄 ui-bundle.zip
        📄 _functions.sh
        📄 _steps.sh
        📄 _dump.sh
        📄 _params.sh
        📄 install.sh (5)
    📂 pdf-theme (6)
        📄 default-theme.yml
        📂 fonts
        📂 images
            📄 techdivision-logo.png
        📄 techdivision-theme.yml
    📂 src (7)
        📄 prepare.php
    📄 .gitignore
    📄 .gitlab-ci.yml (8)
    📄 composer.json
    📄 composer.lock
    📄 met-doc-playbook-local.yml.example (9)
    📄 met-doc-playbook-pacemaker-local.yml.example (10)
    📄 met-doc-playbook-pacemaker-test.yml (11)
    📄 met-doc-playbook-prod.yml (12)
    📄 met-doc-playbook-test.yml (13)
    📄 package-lock.json
    📄 package.json
    📄 README.adoc
    📄 TODO.md

1	Der `build` Ordner beinhaltet alle relevanten Dateien, um sowohl eine lokale, als auch eine remote Installation (Gitlab/Pipeline) zu ermöglichen.
2	Der `bin` Ordner beinhaltet eine `bin/install.sh` Datei. Der `bin/install.sh` wird initial aud dem `build` heraus als CLI Command aufgerufen um dann automatisch die lokaale Antora Instance zu erstellen.
3	Im `assets` Ordner sind die bei der Installation benötigten Files abgelegt und werden dann entsprechend plaziert.
4	Antora Dokumentation Theme Bundles. Die Theme Bundles beinhalten alle relevanten CSS\|JS\|HTML-Templates, die zur HTML Generierung der Dokumentation notwendig sind.
5	Initial wird via bin/install.sh CLI Command die Installation der lokalen Entwicklungsumgebung eingeleitet.
6	Der `pdf-theme` Ordner beinhaltet alle notwendigen Dateien zur Genererierung der Dokumentationen. Diese werden via Gitlab Pipeline gestartet.
7	Der `src` Ordner beinhaltet das PHP Script `prepare.php` zur Genererierung aller benötigten PDFs. Dieses Script wird als eigener Job via Gitlab Pipeline gestartet.
8	Gitlab CI File zum abarbeiten der einzelnen Stages bei den Pipelines.
9	Dieses Playbook wird bei der Installation als Template zur Erstellung des eigentlichen Playbooks zur lokalen Benutzung der Module verwendet.
10	Dieses Playbook wird bei der Installation als Template zur Erstellung des eigentlichen Playbooks zur lokalen Benutzung der Pacemaker Components verwendet.
11	Playbook der neuen Pacemaker Dokumentation.
12	Playbook der remote Modul Test Test Instance.
13	Playbook der aktuellen remote Modul Instance.

Build Installer Struktur

Der Build Installer beinhaltet neben dem build Ordner auch die zusätzlich vom Installer erstellte Ordnerstruktur um eine lokale Entwicklung zu ermöglichen.

📒 <path/to/my/workspace/build-folder> (1)
    📒 build (2)
    📄 gen-pdf.php (3)
    📂 pdf (4)
    📂 public-modules (5)
    📂 public-pacemaker (6)
    📂 repos-modules (7)
        📂 adoc-modul-userguide
        📂 home-doc
        📂 test-modul
    📂 repos-pacemaker (8)
        📂 component-process-pipeline
        📂 main-doc
    📂 repos-pdf (9)
    📂 ui (10)
        📂 theme-docs
            📂 theme
                📂 build
                    📄 ui-bundle.zip (11)
        📂 theme-pacemaker
            📂 theme
                📂 build
                    📄 ui-bundle.zip (11)

1	Main Dokumentation Development Ordner.
2	Antora `build` incl. der Playbooks.
3	[WIP] Falls ein PDF benötigt wird, bietet `gen-pdf.php` die Möglichkeit, für ein Modul/Components local eine PDF zu generieren.
4	Im Ordner PDF wird die generierte PDF abgespeichert.
5	Im Ordner `public-modules` werden die generierten Modul HTML Dokumentationen abgelegt.
6	Im Ordner `public-pacemaker` werden die generierten Pacemaker Components HTML Dokumentationen abgelegt.
7	Im Ordner `repos-modules` werden die Modul Repositories abgelegt.
8	Im Ordner `repos-pacemaker` werden die Pacemaker Components Repositories abgelegt.
9	Der Ordner `repos-pdf` wird bei der PDF Generierung benötigt.
10	Im `ui` Ordner befinden sich die Dokumentation Themes für die Module und Pacemaker Components. Die Theme Location wird im `build/<playbook>.yml` für die jeweilige Konfiguration angegeben.
11	Das Theme Bundle beinhaltet alle relevanten CSS\|JS\|HTML-Templates, die zur HTML Generierung der Dokumentation notwendig sind.

Commands

Installer

Command	Option	Beschreibung
bin/install.sh	-option	Initiale Installationsdatei <my/webspace/antora/folder/build/bin/install.sh>
bin/install.sh	-h\|--help	Hilfe und Beschreibung zu allen existierenden Command Optionen
bin/install.sh	-i\|--install-antora-build	Installieren von Antora
bin/install.sh	-cleanup\|--cleanup-installation	Setzt den Build auf den Urzustand zurück (Es werden alle erstellten Dateien/Ordner entfernt)
bin/install.sh	-params\|--install-params	Auflistung aller Installationsparameter
bin/install.sh	-steps\|--install-steps	Auflistung aller Installation Steps
bin/install.sh	-open\|--open-docs	Öffnen der erstellten Dokumentationen im Browser

Command

Option

Beschreibung

bin/install.sh

-option

Initiale Installationsdatei <my/webspace/antora/folder/build/bin/install.sh>

bin/install.sh

-h|--help

Hilfe und Beschreibung zu allen existierenden Command Optionen

bin/install.sh

-i|--install-antora-build

Installieren von Antora

bin/install.sh

-cleanup|--cleanup-installation

Setzt den Build auf den Urzustand zurück (Es werden alle erstellten Dateien/Ordner entfernt)

bin/install.sh

-params|--install-params

Auflistung aller Installationsparameter

bin/install.sh

-steps|--install-steps

Auflistung aller Installation Steps

bin/install.sh

-open|--open-docs

Öffnen der erstellten Dokumentationen im Browser

Antora

Command	Option	Beschreibung
antora <localPlaybookFileName.yml>	--stacktrace --clean	Command zum starten des Antora Setups
antora <localPlaybookFileName.yml>	--stacktrace	Tracken von Fehlermeldungen beim parsen der adoc files inkl. aller empfohlenen Options
antora <localPlaybookFileName.yml>	--clean	Antora Cache leeren

Command

Option

Beschreibung

antora <localPlaybookFileName.yml>

--stacktrace --clean

Command zum starten des Antora Setups

antora <localPlaybookFileName.yml>

--stacktrace

Tracken von Fehlermeldungen beim parsen der adoc files inkl. aller empfohlenen Options

antora <localPlaybookFileName.yml>

--clean

Antora Cache leeren

Installation Steps

Installieren des `build` Repositories

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

Navigieren zum lokalen Workspace Ordner

cd /Users/myUserName/myWebspaceFolder

Erstellen des Antora Workspace Ordner mit dem Namen ihrer Wahl

mkdir myAntoraWorkFolder

Wechseln zum gerade erstellten Antora Workspace Ordner

cd myAntoraWorkFolder

Clonen des Antora Builds

git clone https://gitlab.met.tdintern.de/met/devdocs/antora/build.git

Nach dem clonen des build Repositories, nun in den build Ordner navigieren , damit wir den Installer starten können.

cd build

Run Antora Installer

bin/install.sh -i (1)

mit -i wird der Installer gestartet.

Es werden nun diverse automatisch generierte Parameter angezeigt, die zum einen vordefinierte Attributes aufzeigen, aber auch die lokalen Installationspfade und Hosts.
Um den Installer nun entgütig zu starten bitte mit y bestätigen
Der Installer durchläuft nun alle notwendigen Steps um die Antora Umgebung vollständig zu erstellen

Um zu ermöglichen, die local Hosts zu erstellen, muss während des Installationsprozesses mit der Eingabe ihres lokalen Passwortes valet.sh die Erlaubnis gegeben werden auf das System zuzugreifen.

Initial wird beim Installer auch das Antora Playbook 1x gestartet und durchlaufen. Somit sind nun alle generierten HTML Files vorhanden und die Dokumentationen sind nun am Browser ihrer Wahl abrufbar.

Initiales öffnen der HTML Dokumentationen im Browser

bin/install.sh -open

Aufbau des lokalen Module Playbooks (Beispiel)

# ----------------------------------------------------------
# output folder, and caching settings
# ----------------------------------------------------------
output:
  clean: true (1)
  dir: ../public-modules (2)
runtime:
  cache_dir: ../.cache (3)
  fetch: true
# ----------------------------------------------------------
# site definition
# ----------------------------------------------------------
site:
  title: "" (4)
  url: https://td-docs.test (5)
  start_page: modules::index.adoc (6)
  robots: disallow (7)
  keys:
    google_analytics:  (8)
# ---------------------------------------------------------
# recources of moduls
# ----------------------------------------------------------
content:
  sources:
    # main local antora start module
    - url: ../repos-modules/home-doc (9)
      branches: HEAD (10)

    - url: ../repos-modules/test-modul (9)
      branches: HEAD (10)

    - url: ../repos-modules/adoc-modul-userguide (9)
      branches: HEAD (10)
# ----------------------------------------------------------
# theme: including local ui bundling process
# ----------------------------------------------------------
ui:
  bundle:
    url: ../ui/theme-docs/theme/build/ui-bundle.zip (11)
    snapshot: true
# ----------------------------------------------------------
# general global attributes
# ----------------------------------------------------------
asciidoc:
  attributes:
    # adoc page attributes: global (12)
    idprefix: ""
    idseparator: "-"
    experimental: ""
    page-pagination: true
    imagesdir: ./images
    # docsearch for pacemaker (13)
    td-pacemaker-docsearch: true
    # custom TD attributes: global, for future custom page attributes add the prefix page- to  new attributes (14)
    td-cookie-consent: true

1	Sowohl beim Antora run command, als auch hier kann eingestellt werden, dass bei jeder Ausführung der Antora Cache geleert wird.
2	Lokaler Speicherort der generierten HTML Dateien. Antora kopiert beim run command alle erstellten HTML Dateien in diesen angegebenen Speicherort.
3	Lokaler Speicherort der temporären Cache Dateien.
4	Titel der Antora Dokumentation, bleibt leer.
5	Die lokale Url der Dokumentation (Die Url wird bei der Installation via `valet.sh` erstellt).
6	Falls notwendig, kann hier die finale Startseite der Dokumentation angegeben werden.
7	Tracking Einstellung der `robots.txt`.
8	Google Analytics ID-Nummer.
9	Angabe des benötigten Repositories eines Dokumentation Moduls, oder aber der lokale pfad, indem sich das Repo befindet.
10	Unter Angabe des Branches kann gesteuert werden welche Version… verwendet wird. Lokal bitte immer `[HEAD]` angeben, ausgenommen, beim lokalen Antora Start Modul.
11	Dokumentation Theme Location.
12	Global Site wide gesetzte Antora Attribute.
13	Eigendefinierte Antora Site Attribute zum steuern der Module DocSearch.
14	Eigendefinierte Antora Site Attribute zum steuern des Cookie Consents.

Local Antora Installer

Beschreibung

Struktur

Commands

Installer

Antora

Installation Steps

Installieren des build Repositories

Run Antora Installer

Aufbau des lokalen Module Playbooks (Beispiel)

WIR HÄTTEN IHNEN DIESE MELDUNG AUCH GERNE ERSPART ...

Installieren des `build` Repositories