Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Online-Dokumentation für Nutzer mit AsciiDoc und Antora

Online-Dokumentation für Nutzer mit AsciiDoc und Antora

Antora erstellt Dokumentations-Websites für Nutzer. Gemäß des Docs-as-Code-Ansatzes werden alle Inhalte in AsciiDoc-Dateien in Git-Repositories versioniert und über CI/CD publiziert.

Die Nutzer erhalten eine übersichtliche Darstellung der Dokumentation im Browser mit Navigationsleiste, Suche und Querverweisen. Sie können zwischen verschiedenen Versionen der Dokumentation hin- und herschalten, um die für sie passenden Informationen zu finden. Open-Source-Projekte wie Camel, Debezium und Couchbase nutzen diese Lösung bereits.
Entwickler und Autoren der Dokumentation bearbeiten die Inhalte wie gewohnt in ihrer IDE und versionieren die Inhalte in der Versionsverwaltung mit Git. Alle Änderungen durchlaufen die bestehenden Code-Review- und Build-Prozesse des Projekts.

Dieser Vortrag stellt die Grundlagen eines Antora-Setups vor und zeigt alle Schritte von einer Dokumentationsänderung in der IDE bis hin zur aktualisierten Dokumentations-Website mit Continuous Integration und Delivery.

Alexander Schwartz

June 20, 2022
Tweet

More Decks by Alexander Schwartz

Other Decks in Programming

Transcript

  1. Online-Dokumentation für Nutzer
    mit AsciiDoc® und Antora
    Alexander Schwartz, Principal Software Engineer
    ObjektForum (OnlineEdition) | 2022-06-20

    View Slide

  2. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 2
    Online-Dokumentation für Nutzer mit AsciiDoc und Antora
    Dokumentation unterstützt die Nutzer
    1.
    AsciiDoc and Antora in Aktion
    2.
    Einrichten von Antora
    3.
    Zusammenfassung
    4.

    View Slide

  3. 3
    Motivation
    Inhalte sind aktuell.
    Inhalte sind konsistent.
    Neue Funktionen und ihre Dokumentation sind gleichzeitig live.
    CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz
    Dokumentation unterstützt die Nutzer bei ihrer Arbeit

    View Slide

  4. • Online, automatisiert, aktuell
    • Durchsuchbar and themen-basiert
    • Navigation und Querverweise
    • Gruppiert nach Version
    und Komponente
    CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 4
    Dokumentation unterstützt die Nutzer bei ihrer Arbeit
    Warum AsciiDoc und Antora

    View Slide

  5. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 5
    Online-Dokumentation für Nutzer mit AsciiDoc und Antora
    Dokumentation unterstützt die Nutzer
    1.
    AsciiDoc and Antora in Aktion
    2.
    Einrichten von Antora
    3.
    Zusammenfassung
    4.

    View Slide

  6. 6
    CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz
    Antora liefert Struktur und Werkzeuge zur Automatisierung
    • Strukturiert Dokumentation in Komponenten und Module
    • Sammelt AsciiDoc-Inhalte aus verschiedenen Git-Repositories und
    Branches
    • Konvertiert AsciiDoc Inhalte in HTML
    • Verbindet das HTML mit dem UI Theme und erzeugt eine statische
    Web-Site
    Hauptvorteile:
    • Schnelle Konvertierung auf Basis von Node.js mit wenigen abhängigen
    Modulen
    • Modular und erweiterbar

    View Slide

  7. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 7
    AsciiDoc ist die Sprache, Asciidoctor ist das Werkzeug
    Asciidoctor
    https://asciidoctor.org/
    AsciiDoc®
    • Schreiben ohne Ablenkung
    mit einfachem Text
    • Großer Funktionsumfang für
    technische Dokumentation
    • Seit über 15 Jahren verfügbar
    und weiterentwickelt
    • Standardisierung in 2020 bei
    der Eclipse Foundation
    begonnen
    Asciidoctor
    • Werkzeug, das aus den
    AsciiDoc-Textdateien HTML
    und viele andere Format
    erstellt
    • Open Source
    • Läuft in Java, Ruby und
    JavaScript
    Laufzeitumgebungen
    • Genutzt von Antora für die
    AsciiDoc-zu-HTML
    Konvertierung
    https://asciidoc-wg.eclipse.org/

    View Slide

  8. • Fokussiert bleiben und die Anwendung
    nicht wechseln
    • Zusammenarbeit über die
    Versionsverwaltung
    • IntelliJ AsciiDoc Plugin
    bietet Unterstützung für Antora und
    AsciiDoc
    CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 8
    Schreiben in der IDE
    List of editors:
    https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/

    View Slide

  9. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 9
    Online-Dokumentation für Nutzer mit AsciiDoc und Antora
    Dokumentation unterstützt die Nutzer
    1.
    AsciiDoc and Antora in Aktion
    2.
    Einrichten von Antora
    3.
    Zusammenfassung
    4.

    View Slide

  10. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 10
    Antora: Struktur
    • Mehrere unabhängige Components
    • Components definiert über Name and Version
    • Jede Component kann mehrere Module haben
    • Jedes Modul hat vordefinierte Gruppen (families) für Seiten
    (pages), Bilder (images), Beispiele (examples), Anhänge
    (attachments) und Abschnitte, die an mehreren Stellen
    eingebunden werden können (partials)
    Erweitere Funktion:
    Komponenten können über mehrere Ordner, Branches und
    Repositories verteilt werden.
    Component
    images
    pages partials
    Module
    … …

    View Slide

  11. Git Repo
    CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 11
    Antora: Ablauf
    Was die Nutzer machen:
    1. Antora starten
    Was Antora macht:
    1. Antora Playbook laden mit der Liste der Repositories und
    Branches
    2. Git Repository clonen
    3. AsciiDoc in HTML wandeln
    4. Mit UI-Theme und UI-Anpassungen verbinden
    5. Optional: Suchindex erstellen
    6. Im Ausgabeverzeichnis eine statische Website erstellen
    Playbook
    Git Repo Antora
    Static Site
    UI Theme

    View Slide

  12. Rolle Professionelle Fähigkeiten Technische Fähigkeiten
    Autor Strukturieren und Schreiben • Git (für die Zusammenarbeit mit anderen
    Autoren)
    • AsciiDoc (um Inhalte zu erstellen)
    CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 12
    Antora: Rollen

    View Slide

  13. Rolle Professionelle Fähigkeiten Technische Fähigkeiten
    Autor Strukturieren und Schreiben • Git (für die Zusammenarbeit mit anderen
    Autoren)
    • AsciiDoc (um Inhalte zu erstellen)
    Docu Ops Automatisierung und Infrastruktur • Git (für die erstmalige Einrichtung)
    • YAML (für die Konfiguration)
    • package.json (für Versionsmanagement)
    • Continuous Integration (für Automatisierung)
    CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 13
    Antora: Rollen

    View Slide

  14. Rolle Professionelle Fähigkeiten Technische Fähigkeiten
    Autor Strukturieren und Schreiben • Git (für die Zusammenarbeit mit anderen
    Autoren)
    • AsciiDoc (um Inhalte zu erstellen)
    Docu Ops Automatisierung und Infrastruktur • Git (für die erstmalige Einrichtung)
    • YAML (für die Konfiguration)
    • package.json (für Versionsmanagement)
    • Continuous Integration (für Automatisierung)
    Web Developer Web Site Erstellung • HTML/CSS (um das Antora Theme anzupassen)
    CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 14
    Antora: Rollen

    View Slide

  15. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz
    Autor:
    1. Erstellt erste Ordner-Struktur für erste Component
    2. Erstellt antora.yml und vergibt Name und Version
    3. Erstellt index.adoc im Verzeichnis pages
    4. Erstellt Navigationseinträge in nav.adoc und fügt es zu antora.yml
    hinzu
    Docu Ops:
    1. Installiert Antora (z. B. npm CLI oder package.json)
    2. Erstellt Playbook für den Autor für eine lokale Vorschau
    3. Erstellt Playbook das die Website für das Internet erstellt
    Web Developer:
    1. Kopiert das bestehende UI-Theme (oder erstellt ein eigenes)
    2. Legt UI-Anpassungen im Ordner supplemental_ui ab.
    15
    Antora: Erste Schritte
    📒 my-component
    ├─📄 antora.yml
    └─📂 modules
    ├─📂 ROOT
    │ ├─📂 attachments
    │ ├─📂 examples
    │ ├─📂 images
    │ ├─📂 pages
    │ │ └─📄 index.adoc
    │ ├─📂 partials
    │ └─📄 nav.adoc
    └─📂 a-named-module
    └─📂 pages
    Quick Start Guide:
    https://docs.antora.org/antora/latest/install-and-run-quickstart/

    View Slide

  16. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 16
    Zeit für eine Live-Demo!
    Wie alles zusammenspielt am Beispiel des
    IntelliJ AsciiDoc Plugins.

    View Slide

  17. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 17
    Online-Dokumentation für Nutzer mit AsciiDoc und Antora
    Dokumentation unterstützt die Nutzer
    1.
    AsciiDoc and Antora in Aktion
    2.
    Einrichten von Antora
    3.
    Zusammenfassung
    4.

    View Slide

  18. 18
    Warum AsciiDoc und Antora
    Inhalte sind aktuell
    durch Zusammenarbeit im Team über Versionskontrolle in Git.
    Inhalte sind konsistent
    durch Komponentenversionen und de-duplizierung von Inhalten.
    Neue Funktionen und ihre Dokumentation sind gleichzeitig live
    durch CI/CD Werkzeuge und automatisiertes Publizieren.
    CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz
    Dokumentation unterstützt die Nutzer bei ihrer Arbeit

    View Slide

  19. AsciiDoc®
    https://asciidoc.org/
    Asciidoctor
    https://asciidoctor.org/
    IntelliJ AsciiDoc Plugin
    https://intellij-asciidoc-plugin.ahus1.de/
    PlantUML
    https://plantuml.com/
    https://real-world-plantuml.com/
    CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 19
    Links
    @ahus1de
    Antora
    https://antora.org/
    Videos, Folien und Beispiele
    https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive
    https://www.ahus1.de/post/cdc-antora-live
    https://www.ahus1.de/post/documentation-site-antora
    Asciidoctor Kroki Extension
    https://github.com/Mogztter/asciidoctor-kroki

    View Slide

  20. Kontakt
    Alexander Schwartz
    Principal Software Engineer
    +49 172 6752068
    [email protected]
    @ahus1de
    CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 20

    View Slide