Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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/

Slide 8

Slide 8 text

• 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/

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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.

Slide 12

Slide 12 text

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. ----

Slide 13

Slide 13 text

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 |===

Slide 14

Slide 14 text

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.

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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/

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

• 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

Slide 23

Slide 23 text

• 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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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/

Slide 28

Slide 28 text

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 @[email protected]

Slide 29

Slide 29 text

Kontakt Alexander Schwartz Principal Software Engineer [email protected] https://www.ahus1.de @ahus1de @[email protected] CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 29