Asciidoctor Deep Dive (Deutsch)

Asciidoctor 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?

5f528a3f6814d28b583f31842e3e8d9e?s=128

Alexander Schwartz

March 17, 2020
Tweet

Transcript

  1. 2.

    Asciidoctor Deep Dive © msg | März 2020 | Asciidoctor

    Deep Dive | Alexander Schwartz 2 Motivation 1 Demo AsciiDoc Syntax und Ökosystem 2 Demo Asciidoctor PDF-Erzeugung 3 Zusammenfassung 4
  2. 3.

    Asciidoctor Deep Dive © msg | März 2020 | Asciidoctor

    Deep Dive | Alexander Schwartz 3 Motivation 1 Demo AsciiDoc Syntax und Ökosystem 2 Demo Asciidoctor PDF-Erzeugung 3 Zusammenfassung 4
  3. 4.

    Motivation Was nutzt ihr, um Dokumente zu schreiben? © msg

    | März 2020 | Asciidoctor Deep Dive | Alexander Schwartz 4 Tool + – Office-Suite
  4. 5.

    Motivation Was nutzt ihr, um Dokumente zu schreiben? © msg

    | März 2020 | Asciidoctor Deep Dive | Alexander Schwartz 5 Tool + – Office-Suite Wiki
  5. 6.

    Motivation Möglichkeiten in einer Continuous Integration/Delivery-Umgebung © msg | März

    2020 | Asciidoctor Deep Dive | Alexander Schwartz 6 Code Snippets Publizieren (auf Website) Druckbare Documentation Änderungen verfolgen Suchen in Documentation De-Duplikation und Wiederverwendung Text APIs Diagramme Tests Share Merge
  6. 7.

    Asciidoctor Versprechen © msg | März 2020 | Asciidoctor Deep

    Dive | Alexander Schwartz 7 • Dokumente ohne Ablenkung in der IDE schreiben • Ausdrucksstarke Syntax • Kollaboration und Versionierung mit Git • Ökosystem nutzen • Verschiedene Eingangsformate für die Dokumentenpipeline • Verschiedene Ausgangsformate aus denselben Quellen https://asciidoctor.org/
  7. 8.

    Asciidoctor Deep Dive © msg | März 2020 | Asciidoctor

    Deep Dive | Alexander Schwartz 8 Motivation 1 Demo AsciiDoc Syntax und Ökosystem 2 Demo Asciidoctor PDF-Erzeugung 3 Zusammenfassung 4
  8. 9.

    Demo AsciiDoc und IDE Unterstützung © msg | März 2020

    | Asciidoctor Deep Dive | Alexander Schwartz 9 Features: • Variablen, Listen, Referenzen, Tabellen • Bedingte Formatierung • Listings, mathematische Formeln, Icons • Diagramme mit PlantUML • Erweiterungen • Unterstützung für Spring REST Docs
  9. 10.

    © msg | März 2020 | Asciidoctor Deep Dive |

    Alexander Schwartz Source: https://doctoolchain.github.io/docToolchain/ Pipeline für Dokumentation mit docToolchain 10
  10. 11.

    Pipeline für Dokumentation mit docToolchain © msg | März 2020

    | Asciidoctor Deep Dive | Alexander Schwartz 11 Source: https://doctoolchain.github.io/docToolchain/
  11. 12.

    Asciidoctor Deep Dive © msg | März 2020 | Asciidoctor

    Deep Dive | Alexander Schwartz 12 Motivation 1 Demo AsciiDoc Syntax und Ökosystem 2 Demo Asciidoctor PDF-Erzeugung 3 Zusammenfassung 4
  12. 13.

    Source: https://asciidoctor.org/docs/asciidoctor-pdf/ https://github.com/asciidoctor/asciidoctor-pdf/issues/20 https://github.com/ahus1/asciidoctor-deepdive/tree/master/manual Demo PDF Erstellung mit Prawn/Asciidoctor PDF

    © msg | März 2020 | Asciidoctor Deep Dive | Alexander Schwartz 13 • Template auswählen • Kopf- und Fußzeile konfigurieren • Titelseite definieren • Übergabe von Attributen z. B. via Maven • Silbentrennung
  13. 14.

    Source: https://github.com/Mogztter/asciidoctor-pdf.js/tree/master/examples/cheat-sheet Demo PDF Erstellung mit Puppeteer/Asciidoctor PDF.js © msg

    | März 2020 | Asciidoctor Deep Dive | Alexander Schwartz 14 • Bestehende Templates vs. individuelle Templates • Design mittels CSS • Basiert auf JavaScript, automatisierbar mit yarn/npm • Individuelle Layouts (zum Beispiel mit Spalten)
  14. 15.

    © msg | März 2020 | Asciidoctor Deep Dive |

    Alexander Schwartz 15 Source: https://github.com/Mogztter/asciidoctor-pdf.js/tree/master/examples/cheat-sheet
  15. 16.

    Asciidoctor Deep Dive © msg | März 2020 | Asciidoctor

    Deep Dive | Alexander Schwartz 16 Motivation 1 Demo AsciiDoc Syntax und Ökosystem 2 Demo Asciidoctor PDF-Erzeugung 3 Zusammenfassung 4
  16. 17.

    Meine Erfahrungen © msg | März 2020 | Asciidoctor Deep

    Dive | Alexander Schwartz 17 • Asciidoctor hat eine gute Dokumentation • Dokumentation kann erstellt werden, ohne dass auf HTML zurückgegriffen wird • Asciidoctor PDF ist in der Ausgabe relativ gut konfigurierbar, kommt aber an seine Grenzen, wenn ein individuelles Layout gefordert ist. Asciidoctor PDF.js erlaubt hier vollständiges HMTL5-styling • Fehlt etwas? Schaue im Asciidoctor Extension Lab nach einer Erweiterung!
  17. 18.

    Asciidoctor Versprechen © msg | März 2020 | Asciidoctor Deep

    Dive | Alexander Schwartz 18 • Dokumente ohne Ablenkung in der IDE schreiben • Ausdrucksstarke Syntax • Kollaboration und Versionierung mit Git • Ökosystem nutzen • Verschiedene Eingangsformate für die Dokumentenpipeline • Verschiedene Ausgangsformate aus denselben Quellen https://asciidoctor.org/
  18. 19.

    Links © msg | März 2020 | Asciidoctor Deep Dive

    | Alexander Schwartz 19 Asciidoctor https://asciidoctor.org Asciidoctor Extension Lab https://github.com/asciidoctor/asciidoctor-extensions-lab PlantUML http://plantuml.com/ https://real-world-plantuml.com/ docToolchain https://doctoolchain.github.io/docToolchain/ @ahus1de Asciidoctor PDF.js https://github.com/Mogztter/asciidoctor-pdf.js Documentation as Code mit Asciidoctor https://heise.de/-4642013 Antora https://antora.org/ Video, Folien und Beispiele https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive
  19. 20.

    .consulting .solutions .partnership Alexander Schwartz Principal IT Consultant +49 171

    5625767 alexander.schwartz@msg.group @ahus1de msg systems ag (Headquarters) Robert-Buerkle-Str. 1, 85737 Ismaning Germany www.msg.group