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

AsciiDoc Deep Dive (Deutsch)

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?

Alexander Schwartz

June 23, 2023
Tweet

More Decks by Alexander Schwartz

Other Decks in Programming

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

    View Slide

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

    View Slide