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