Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Dokumentation schreiben kann spass machen

1,458 views

Published on

Der Vortrag gibt einen Einblick in die Auszeichnungssprache AsciiDoctor und dem Programm zur Erstellung von Dokumenten im HTML und PDF Format. Es wird beschrieben, wie AsciiDoctor zur Dokumentation in Java (JavaDoc) verwendet werden kann. AsciiDoctor kann in die bekannten Build-Tools Ant, Maven und Gradle integriert werden, so dass die Dokumentation wie Quellcode regelmäßig übersetzt wird. Als Ausblick wird die Integration von "beschreibenden Grafikformatken" wie GraphViz und PlantUML in AsciiDoctor Dokumente gezeigt.

Published in: Software
  • Be the first to comment

Dokumentation schreiben kann spass machen

  1. 1. AsciiDoctor Dokumentation schreiben kann Spass machen!
  2. 2. Sebastian Hempel IT-Consulting Hempel @ithempel
  3. 3. Welche Dokumente schreiben Entwickler?
  4. 4. Warum macht das Schreiben keinen Spass?
  5. 5. Was muss anders werden?
  6. 6. AsciiDoctor
  7. 7. AsciiDoc leightweight markup language erste Veröffentlichung im November 2002
  8. 8. AsciiDoctor Implementierung von AsciiDoc in Ruby erste Veröffentlichung im Januar 2013
  9. 9. = Hello, AsciiDoc! Doc Writer <doc@example.com> An introduction to http://asciidoc.org[AsciiDoc]. == First Section * item 1 * item 2 [source,ruby] puts "Hello, World!"</doc@example.com>
  10. 10. direkte Erstellung von HTML5
  11. 11. Ausgabe im DocBook Format
  12. 12. Dan Allen @mojavelinux
  13. 13. Wer nutzt AsciiDoc(tor)
  14. 14. Formatierung *fett* _kursiv_ `nicht proportional`
  15. 15. Listen * Element ** nächstes Ebene * weiteres Element
  16. 16. Checklisten - [ ] noch nicht erledigt - [*] erledigt
  17. 17. Aufzählung . erstes Element . zweites Element .. erstes Unterelement
  18. 18. Labeled Lists Label:: Beschreibung noch ein Label:: eine weitere Beschreibung
  19. 19. Zitate [quote, Bill Gates, Microsoft] ____ 640 KB are enough for everyone. ____
  20. 20. Literal Block .... Jetzt wird alles wie angegeben - ausgegeben. ....
  21. 21. Code Blöcke ---- public class EnterpriseAbstractFactory { public doSomething(int howLong) { Thread.sleep(howLong); } } ----
  22. 22. Callouts ---- public class EnterpriseAbstractFactory { <1> public doSomething(int howLong) { Thread.sleep(howLong); <2> } } ---- <1> to shoort <2> busy waiting please
  23. 23. Codeformatierung [source,java] ---- public class EnterpriseAbstractFactory { public doSomething(int howLong) { Thread.sleep(howLong); } } ----
  24. 24. Codeformatierung ohne Zeilenumbruch [source,java,options="nowrap"] ---- public class EnterpriseAbstractFactory { public doSomething(int howLong) { if (checkSomeThingThatLeadsToAVeryLongLine() == WE_EXPECT_EXACTLY_THIS) { Thread.sleep(howLong); } } } ----
  25. 25. Tabellen |=== | Kopfzeile | mit zweiter Spalte | JDK | 8 | Java EE | 7 |===
  26. 26. Tabellen aus CSV [format="csv",options="header"] |=== Operation System,Software,Version Linux,JDK,8 NoArch,WildFly,8.1 |===
  27. 27. Einbinden von Bildern image::filename.png[A Picture,200,100]
  28. 28. Festlegung des Bilderverzeichnisses :imagesdir: ./img
  29. 29. Inhaltsverzeichnis :toc: :toclevels: 3 :toc-title: Inhaltsverzeichnis :toc-placement!: :sectanchors: :numbered: toc::[]
  30. 30. Integration in Build-Tool
  31. 31. Integration des Plugins ... <plugins> <plugin> <groupid>org.asciidoctor</groupid> <artifactid>asciidoctor-maven-plugin</artifactid> <version>0.1.4</version> ... </plugin> </plugins> ...
  32. 32. Konfiguration des Plugins <plugin> ... <configuration> <sourcedirectory>${basedir}/src/main/doc</sourcedirectory> <outputdirectory>${basedir}/target/docs</outputdirectory> <backend>html</backend> <doctype>book</doctype> </configuration> ... </plugin> ...
  33. 33. Aufruf des Plugins ... <plugin> ... <executions> <execution> <id>output-html</id> <phase>generate-resources</phase> <goals> <goal>process-asciidoc</goal> </goals> </execution> </executions> ... </plugin> ...
  34. 34. Integration in JavaDoc AsciiDoc statt HTML
  35. 35. Integration in JavaDoc-Erstellung <plugin> <groupid>org.apache.maven.plugins</groupid> <artifactid>maven-javadoc-plugin</artifactid> <version>2.9</version> <configuration> <source>1.7 <doclet>org.asciidoctor.Asciidoclet</doclet> <docletartifact> <groupid>org.asciidoctor</groupid> <artifactid>asciidoclet</artifactid> <version>0.1.4</version> </docletartifact> </configuration> </plugin>
  36. 36. Kommentar mit AsciiDoc /** = Example Class * * This ist an example class. * * * This is a List * * This is *bold* or _italic_. */ public class Example { private String attribute; /** * Get some attribute. * * null:: The value might be null. * other:: The name of the attribute. */ public String getAttribute() { } }
  37. 37. AsciiDoctor Plugins
  38. 38. Beispiel AsciiDoctor-Diagram Graphviz PlantUML Ditaa
  39. 39. Installation gem install asciidoctor-diagram
  40. 40. Integration #!/usr/bin/ruby require 'asciidoctor' require 'asciidoctor-diagram/plantuml' Asciidoctor.render_file('sample.adoc', :in_place => true, :safe => 'unsafe')
  41. 41. Integration ab 1.5.x Vorraussetzung: Java (JAVA_HOME) asciidoctor -r asciidoctor-diagram sample.adoc
  42. 42. Beispiel ["plantuml", "asciidoctor-diagram-classes", "png"] ---- interface BlockProcessor class DiagramBlock class DitaaBlock class PlantUmlBlock class GraphvizBlock BlockProcessor <|-- DiagramBlock DiagramBlock <|-- DitaaBlock DiagramBlock <|-- PlantUmlBlock DiagramBlock <|-- GraphvizBlock ----
  43. 43. Bildnachweis (1) Sebastian Hempel / Sebastian Hempel / CC-BY SA (2) document folders / John Keogh / CC-BY NC (3)frustration / Sybren Stüvel / CC-BY NC (4) There are years that ask questions and years that answer. / theunquietlibrarian / CC-BY NC (5) Day 9 / Jay Reed / CC-BY SA (8) Dan Allen / Dan Allen (18) puzzle / Olga Berrios / CC-BY
  44. 44. Creative Commons CC-BY SA

×