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

Dokumentation schreiben kann Spaß machen! (2017)

Dokumentation schreiben kann Spaß machen! (2017)

Warum das Schreiben von Dokumentation mit AsciiDoctor Spaß macht

Sebastian Hempel

June 28, 2017
Tweet

More Decks by Sebastian Hempel

Other Decks in Programming

Transcript

  1. None
  2. 1

  3. 2

  4. None
  5. 3

  6. 4

  7. 5

  8. 6 7 . 2

  9. 7 . 1

  10. 7 . 3 = 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>
  11. 8 . 1 8 . 2

  12. 9 . 1 asciidoctor example.adoc

  13. 9 . 2 asciidoctor -b docbook5 example.adoc

  14. 9 . 3 asciidoctor -b pdf -r asciidoctor-pdf example.adoc

  15. None
  16. 10 . 1

  17. 10 . 2 11 *fett* _kursiv_ `monospace`

  18. 12 . 1 * Element ** nächste Elementebene * weiteres

    Element
  19. 12 . 2 - [ ] zu erledigen - [*]

    erledigt
  20. 12 . 3 . erstes Element . zweites Element ..

    erstes Unterelement
  21. 12 . 4 Label:: Beschreibung Definition:: eine weitere Beschreibung

  22. 13 . 1 [quote, Bill Gates, Microsoft] ____ 640 KB

    are enough for everyone. ____
  23. 13 . 2 .... Jetzt wird alles wie angegeben -

    ausgegeben. ....
  24. [source, java] ---- public class EnterpriseAbstractFactory { public doSomething(int howLong)

    { Thread.sleep(howLong); } } ----
  25. 13 . 3 [source, java] ---- public class EnterpriseAbstractFactory {

    <1> public doSomething(int howLong) { Thread.sleep(howLong); <2> } } ---- <1> to short <2> busy waiting please
  26. 13 . 4 13 . 5 TIP: Wir programmieren für

    andere Programmierer nicht den Compiler.
  27. 14 . 1 |=== | Kopfzeile | mit zweiter Spalte

    | JDK | 8 | Java EE | 7 |===
  28. 14 . 2 [format="csv",options="header"] |=== Operation System,Software,Version Linux,JDK,8 NoArch,WildFly,8.1 |===

  29. 15 image::catcontent.jpg[Cat]

  30. 16 :toc: :toclevels: 3 :toc-title: Inhaltsverzeichnis :toc-placement!: :sectanchors: :numbered: toc::[]

  31. 17 . 1 [source, java] ---- include::hello.java[] ----

  32. [source, java] ---- include.hello.java[tags=main] ---- class Hello { // tag::main[]

    public static int main() { ... } // end::main[] }
  33. 17 . 2

  34. 18 . 1 18 . 2

  35. None
  36. 19 . 1 19 . 2 ... <plugins> <plugin> <groupid>org.asciidoctor</groupid>

    <artifactid>asciidoctor-maven-plugin</artifactid> <version>1.5.5</version> ... </plugin> </plugins>
  37. <plugin> ... <configuration> <sourcedirectory>${basedir}/src/docs/asciidoc</sourcedirectory> <outputdirectory>${basedir}/target/docs</outputdirectory> <backend>html</backend> <doctype>book</doctype> </configuration> ... </plugin>

  38. 19 . 3 <plugin> ... <executions> <execution> <id>output-html</id> <phase>generate-resources</phase> <goals>

    <goal>process-asciidoc</goal> </goals> </execution> </executions> ... </plugin>
  39. 19 . 4 buildscript { dependencies { classpath 'org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.15' classpath

    'org.asciidoctor:asciidoctorj-diagram:1.5.4' classpath 'org.ysb33r.gradle:vfs-gradle-plugin:1.0' classpath 'commons-httpclient:commons-httpclient:3.1' } } plugins { id 'java' id 'org.asciidoctor.convert' version '1.5.3' id 'com.github.jruby-gradle.base' version '1.4.0' id 'org.ysb33r.vfs' version '1.0' } dependencies { gems 'rubygems:slim:3.0.8' gems 'rubygems:thread_safe:0.3.5' } ext { revealjsVersion = '3.3.0' asciidoctorBackendVersion = 'master' downloadDir = new File(buildDir,'download')
  40. 19 . 5 <plugin> <groupid>org.apache.maven.plugins</groupid> <artifactid>maven-javadoc-plugin</artifactid> <version>2.9</version> <configuration> <source>1.7</source> <doclet>org.asciidoctor.Asciidoclet</doclet>

    <docletartifact> <groupid>org.asciidoctor</groupid> <artifactid>asciidoclet</artifactid> <version>1.5.4</version> </docletartifact> </configuration> </plugin>
  41. 20 . 1 /** = 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() { } }
  42. 20 . 2

  43. 21 . 2

  44. 21 . 1 [plantuml, target="asciidoctor-diagram-classes", "png"] ---- interface BlockProcessor class

    DiagramBlock class DitaaBlock class PlantUmlBlock class GraphvizBlock BlockProcessor <|-- DiagramBlock DiagramBlock <|-- DitaaBlock DiagramBlock <|-- PlantUmlBlock DiagramBlock <|-- GraphvizBlock ----
  45. 21 . 3

  46. 21 . 4 [ditaa, target="puppet-git-architecture"] ---- +----------------+ | Puppet-Server |

    | Workspace | +----------------+ | +-------+ | {s} | | | | | | Git | +-------+ ^ | | +---------------------+--------------------+ | | | | push | push | push +-------+ +-------+ +-------+ | {s} | | {s} | | {s} | | | | | | | | | | | | | | Git | | Git | | Git | +-------+ +-------+ +-------+ | | | +----------------+ +----------------+ +----------------+ | Entwickler 1 | | Entwickler 2 | | Entwickler 3 |
  47. 21 . 5

  48. 21 . 6

  49. 22 . 1 gem 'jekyll', '~> 3.4' gem 'asciidoctor', '>=

    1.5.5' gem 'coderay', '>= 1.1.1' gem 'pygments.rb', '>= 0.6.3' group :jekyll_plugins do gem 'jekyll-sitemap', '>= 0.10.0' gem 'jekyll-tagging-related_posts', '>= 0.2.1' gem 'jekyll-asciidoc', '= 2.0.1' gem 'asciidoctor-diagram', '>= 1.5.2' end
  50. 22 . 2 --- layout: post title: 'Asciidoctor - Werkzeug

    zur Erstellung von technischen Dokumenten' excerpt: 'Seitdem ich AsciiDoctor kennen gelernt habe, schreibe ich technisc category: software-development tags: [documentation,markup] cc-license: by-sa date: 2014-03-03 09:22:00 +0100 modified: 2016-03-20 comments: false --- = Asciidoctor - Werkzeug zur Erstellung von technischen Dokumenten :icons: font Kein Entwickler / kein Administrator erstellt gerne Dokumentation. Auch ich kann mir angenehmere Tätigkeiten vorstellen. Allerdings habe ich mich auch schon oft geärgert, bestimmte Dinge nicht doku Durch dem Einsatz von Asciidoctor könnte das Erstellen von technischen Dokum
  51. 22 . 3

  52. 22 . 4