AsciiDoc Deep Dive (Deutsch)

Mit AsciiDoc kann Dokumentation im gleichen Repository wie der Quellcode des Programms eingecheckt werden. Damit kann die Dokumentation in AsciiDoc zusammen mit der Funktionalität im Code mit jeder umgesetzten User-Story mitwachsen.

Für IDEs gibt es Plug-ins, die eine Vorschau für die erstellten Texte ermöglichen und Refactorings der erstellten Dokumente erlauben. Der Continuous-Integration-Server erstellt anschließend aus den AsciiDoc-Dateien die HTML- oder PDF-Dokumente für die Nutzer.

Ihr habt schon erste Erfahrungen mit AsciiDoc gesammelt und wollt mehr erfahren?

Dieser Vortrag geht in die Details und beantwortet folgende Fragen:

* Wie strukturiere ich große Dokumente?
* Wie kann ich mit PlantUML schönere Grafiken erzeugen?
* Wie binde ich Quellen ein und nutze Querverweise?
* Was ist im Styling von PDFs möglich?
* Wie funktioniert Silbentrennung?
* Wie kann mich meine IDE unterstützen?

Transcript

1. AsciiDoc® Deep Dive
   Alexander Schwartz, Principal Software Engineer @ Red Hat
   betterCode() ArchDoc | 2023-06-26
   

   View Slide

2. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 2
   AsciiDoc Deep Dive
   Motivation
   1
   Demo AsciiDoc Syntax und Ökosystem
   2
   Demo Asciidoctor PDF-Erzeugung
   3
   Zusammenfassung
   4
   

   View Slide

3. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 3
   AsciiDoc Deep Dive
   Motivation
   1
   Demo AsciiDoc Syntax und Ökosystem
   2
   Demo Asciidoctor PDF-Erzeugung
   3
   Zusammenfassung
   4
   

   View Slide

4. Tool + –
   Office-Suite
   CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 4
   Was nutzt ihr, um Dokumente zu schreiben?
   Motivation
   

   View Slide

5. Tool + –
   Office-Suite
   Wiki
   CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 5
   Was nutzt ihr, um Dokumente zu schreiben?
   Motivation
   

   View Slide

6. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 6
   Möglichkeiten in einer Continuous Integration/Delivery-Umgebung
   Motivation
   Code Snippets
   Publizieren
   (auf Website) Druckbare
   Dokumentation
   Änderungen
   verfolgen
   Suchen in
   Documentation
   De-Duplikation
   und Wiederverwendung
   Text
   APIs
   Diagramme
   Tests
   Share Merge
   

   View Slide

7. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 7
   AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung
   Asciidoctor
   https://asciidoctor.org/
   AsciiDoc®
   • fokussiertes Schreiben
   ohne Ablenkung
   • hat alles was technische
   Dokumentation benötigt
   • 15 Jahre alt und sehr
   lebendig
   • Standardisierung in 2020
   bei Eclipse Foundation
   gestartet
   Asciidoctor
   • Implementierung um HTML
   und PDFs aus AsciiDoc-
   Dateien zu erzeugen
   • OpenSource
   Implementierung
   • Läuft mit Java, Ruby und
   JavaScript
   • kann z. B. in Maven und
   Gradle Builds über Plugins
   integriert werden
   https://asciidoc-wg.eclipse.org/
   

   View Slide

8. • Dokumente ohne Ablenkung in der
   Entwicklungsumgebung schreiben
   • Kollaboration und Versionierung mit Git
   • Vorlagen liefern Hilfen und Struktur
   • Nahtloses Einbinden in Continuous
   Delivery Prozesse
   CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 8
   Technische Dokumentation als Teil des Entwicklungsprozesses
   Liste der Editoren:
   https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
   

   View Slide

9. Asciidoctor Deep Dive
   CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 9
   Motivation
   1
   Demo AsciiDoc Syntax und Ökosystem
   2
   Demo Asciidoctor PDF-Erzeugung
   3
   Zusammenfassung
   4
   

   View Slide

10. Features:
    • Variablen, Listen, Referenzen, Tabellen
    • Bedingte Formatierung
    • Listings, mathematische Formeln, Icons
    • Diagramme mit PlantUML
    • Erweiterungen
    • Unterstützung für Spring REST Docs
    CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 10
    Demo AsciiDoc und IDE Unterstützung
    

    View Slide

11. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 11
    Demo AsciiDoc Syntax und Ökosytem
    Texte und Listen
    Each sentence should be in a separate line.
    Every blank line creates a new paragraph.
    You can write *bold* text.
    _Italic_ works as well text.
    Lists
    . work
    . with
    . dots
    to make them numbered and
    * asterisks
    * to
    * make
    bullet points.
    

    View Slide

12. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 12
    Demo AsciiDoc Syntax und Ökosytem
    Abschnitte und Auszeichnungen
    [IMPORTANT]
    --
    You can mark a paragraph to be important.
    --
    TIP: There is also the shorter one-line-
    syntax.
    ====
    This is an example block. Use it to
    provide examples to your users.
    ====
    ----
    This is a listing.
    You can provide syntax highlighting for
    XML/Java etc. here.
    ----
    

    View Slide

13. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 13
    Demo AsciiDoc Syntax und Ökosytem
    Tabellen
    Tables are blocks, `|===` marks their
    beginning and end.
    .Table title
    [cols="1,1,3a,1"]
    |===
    |H1 |H2 |H3 |H4
    |Cell 1
    |Cell 2
    |Formatting *of words* works like in
    _before_ if you switch the column or
    cell to AsciiDoc format.
    |Cell 4
    |===
    

    View Slide

14. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 14
    Demo AsciiDoc Syntax und Ökosytem
    Bilder
    Images can be in-line and as blocks.
    An image:file.svg[pdfwidth=3cm] image in-
    line.
    An image with a caption:
    .This is an image
    image::file.svg[]
    For schematic drawings prefer to use SVG
    images for best results on the Web and in
    PDFs.
    

    View Slide

15. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 15
    Demo AsciiDoc Syntax und Ökosytem
    Grafiken am Beispiel PlantUML
    To store diagrams as text, have a look at
    PlantUML:
    .Diagrams can have a caption as well.
    plantuml::showcase_swimlanes.puml[swimlanes,svg]
    @startuml
    skinparam shadowing false
    |Component with Web-UI|
    start
    :User opens web page;
    :Forward to authentication;
    |#AntiqueWhite|Authentication|
    :Authenticate with user name\nand password;
    :Forward to Web-UI;
    |Component with Web-UI|
    :Open Web-UI;
    stop
    @enduml
    

    View Slide

16. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 16
    Demo AsciiDoc Syntax und Ökosytem
    Quellcode-Beispiele einbinden
    .Standard include
    [source,java]
    ----
    include::Example.java[]
    ----
    :icons: font
    .Pick a block with callout
    [source,java,indent=0]
    ----
    include::Example.java[tag=sop]
    ----
    <1> this is your first line of Java
    

    View Slide

17. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 17
    Pipeline für Dokumentation mit docToolchain
    Source: https://doctoolchain.github.io/docToolchain/
    

    View Slide

18. 18
    Source: https://doctoolchain.github.io/docToolchain/
    

    View Slide

19. 19
    Dokumentation unterstützt die Nutzer bei ihrer Arbeit
    Warum AsciiDoc und Antora
    • Online, automatisiert, aktuell
    • Durchsuchbar and themen-basiert
    • Navigation und Querverweise
    • Gruppiert nach Version
    und Komponente
    CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz
    

    View Slide

20. 20
    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
    CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz
    

    View Slide

21. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 21
    Asciidoctor Deep Dive
    Motivation
    1
    Demo AsciiDoc Syntax und Ökosystem
    2
    Demo Asciidoctor PDF-Erzeugung
    3
    Zusammenfassung
    4
    

    View Slide

22. • Template auswählen
    • Kopf- und Fußzeile konfigurieren
    • Titelseite definieren
    • Übergabe von Attributen z. B. via Maven
    • Silbentrennung
    CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 22
    Demo PDF Erstellung mit Prawn/Asciidoctor PDF
    Source:
    https://asciidoctor.org/docs/asciidoctor-pdf/
    https://github.com/asciidoctor/asciidoctor-pdf/issues/20
    https://github.com/ahus1/asciidoctor-deepdive/tree/master/manual
    

    View Slide

23. • Bestehende Templates vs.
    individuelle Templates
    • Design mittels CSS
    • Basiert auf JavaScript,
    automatisierbar mit yarn/npm
    • Individuelle Layouts
    (zum Beispiel mit Spalten)
    CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 23
    Demo PDF Erstellung mit Puppeteer/Asciidoctor Web PDF
    Source: https://github.com/Mogztter/asciidoctor-pdf.js/tree/master/examples/cheat-sheet
    

    View Slide

24. Source: https://github.com/Mogztter/asciidoctor-pdf.js/tree/master/examples/cheat-sheet
    CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 24
    

    View Slide

25. 25
    Warum AsciiDoc
    Aktuelle und korrekte Inhalte
    durch Zusammenarbeit als Team über die Versionsverwaltung intelligente IDEs
    Konsistenz über verschiedene Dokumente hinweg
    durch Publikation von verschiedenen Formaten wie HTML und PDF,
    De-Duplikation und Wiederverwendung
    Lieferung neuer Funktionen inklusive Dokumentation
    durch automatisierte Erstellung der Dokumente oder als Teil von Websites
    CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz
    AsciiDoc fördert Zusammenarbeit, De-Duplikation und Automatisierung
    

    View Slide

26. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 26
    Asciidoctor Deep Dive
    Motivation
    1
    Demo AsciiDoc Syntax und Ökosystem
    2
    Demo Asciidoctor PDF-Erzeugung
    3
    Zusammenfassung
    4
    

    View Slide

27. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 27
    AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung
    AsciiDoc
    • fokussiertes Schreiben
    ohne Ablenkung
    • hat alles was technische
    Dokumentation benötigt
    • 15 Jahre alt und sehr
    lebendig
    • Standardisierung in 2020
    bei Eclipse Foundation
    gestartet
    Asciidoctor
    • Implementierung um HTML
    und PDFs aus AsciiDoc-
    Dateien zu erzeugen
    • OpenSource
    Implementierung
    • Läuft mit Java, Ruby und
    JavaScript
    • kann z. B. in Maven und
    Gradle Builds über Plugins
    integriert werden
    https://asciidoc-wg.eclipse.org/
    Asciidoctor
    https://asciidoctor.org/
    

    View Slide

28. AsciiDoc
    https://asciidoc.org
    Asciidoctor
    https://asciidoctor.org
    IntelliJ AsciiDoc Plugin
    https://ahus1.de/post/technical-writing-udemy
    PlantUML
    http://plantuml.com/
    https://real-world-plantuml.com/
    docToolchain
    https://doctoolchain.github.io/docToolchain/
    Links
    CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 28
    @ahus1de
    Asciidoctor Web PDF
    https://github.com/ggrossetie/asciidoctor-web-pdf
    Documentation as Code mit Asciidoctor
    https://heise.de/-4642013
    Antora
    https://antora.org/
    https://www.ahus1.de/post/documentation-site-antora
    Video, Folien und Beispiele
    https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive
    @ahus1@fosstodon.org
    

    View Slide

29. Kontakt
    Alexander Schwartz
    Principal Software Engineer
    alexander.schwartz@gmx.net
    https://www.ahus1.de
    @ahus1de
    @ahus1@fosstodon.org
    CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 29
    

    View Slide