writing documentation with asciidoctor - eclipsecon 2020 · 2017-12-06 · farben: 254/153/21...
Post on 06-Aug-2020
5 Views
Preview:
TRANSCRIPT
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 42 Untertitel: Calibri, 24
Special ( entfernen): Untertitel über Logo ziehen
Jérémie Bresson – 03.11.2015
Writing documentation with Asciidoctor
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Text: Calibri, Fett, 42
AsciiDoc
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
AsciiDoc example
= Getting Started with Java
Author Name <author@example.org>
== Hello World example
Copy the *HelloWorld.java* file.
TIP: The application prints _Hello World!_ to the console.
* Compile this source to a class file using `javac`.
* Run the compiled class file using `java`.
If you need help with the Java syntax check the
link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
AsciiDoc example
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
AsciiDoc example
= Getting Started with Java
Author Name <author@example.org>
== Hello World example
Copy the *HelloWorld.java* file.
TIP: The application prints _Hello World!_ to the console.
* Compile this source to a class file using `javac`.
* Run the compiled class file using `java`.
If you need help with the Java syntax check the
link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Headings
= Getting Started with Java
Author Name <author@example.org>
== Hello World example
Copy the *HelloWorld.java* file.
TIP: The application prints _Hello World!_ to the console.
* Compile this source to a class file using `javac`.
* Run the compiled class file using `java`.
If you need help with the Java syntax check the
link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
Document Title
Section Level 1
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
= Getting Started with Java
Author Name <author@example.org>
== Hello World example
Copy the *HelloWorld.java* file.
TIP: The application prints _Hello World!_ to the console.
* Compile this source to a class file using `javac`.
* Run the compiled class file using `java`.
If you need help with the Java syntax check the
link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
Lists
Unordered list items
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Inline formatting
= Getting Started with Java
Author Name <author@example.org>
== Hello World example
Copy the *HelloWorld.java* file.
TIP: The application prints _Hello World!_ to the console.
* Compile this source to a class file using `javac`.
* Run the compiled class file using `java`.
If you need help with the Java syntax check the
link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
bold
italic
code
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
= Getting Started with Java
Author Name <author@example.org>
== Hello World example
Copy the *HelloWorld.java* file.
TIP: The application prints _Hello World!_ to the console.
* Compile this source to a class file using `javac`.
* Run the compiled class file using `java`.
If you need help with the Java syntax check the
link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
Links
link with title
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
= Getting Started with Java
Author Name <author@example.org>
== Hello World example
Copy the *HelloWorld.java* file.
TIP: The application prints _Hello World!_ to the console.
* Compile this source to a class file using `javac`.
* Run the compiled class file using `java`.
If you need help with the Java syntax check the
link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
Admonition
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Text: Calibri, Fett, 42
Asciidoctor
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Asciidoctor is publishing toolchain for the AsciiDoc writing format.
Written in Ruby (and transpiled to JavaScript) (can be used with JRuby in the JVM)
Open Source (MIT Licence)
Asciidoctor
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Multiple Outputs
HTML pages
Eclipse Help guides
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Text: Calibri, Fett, 52
Special: « Alt+0171 » Alt+0187
«Why is asciidoctor a great tool?»
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Text: Calibri, Fett, 42
Source code listings
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
A code snippet in your documentation
== Usage of Mylyn wikitext
With the method `toHtml(String)` in <<lst-wikitext1>> you
can convert a text from Mediawiki Language to HTML.
[[lst-wikitext1, Listing 1]]
[source,java]
----
public static String toHtml(String mediawikiText) {
StringWriter writer = new StringWriter();
MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), new HtmlDocumentBuilder(writer));
parser.parse(mediawikiText);
return writer.toString();
}
----
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Callout
== Usage of Mylyn wikitext
With the method `toHtml(String)` in <<lst-wikitext1>> you
can convert a text from Mediawiki Language to HTML.
[[lst-wikitext1, Listing 1]]
[source,java]
----
public static String toHtml(String mediawikiText) {
StringWriter writer = new StringWriter();
MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), new HtmlDocumentBuilder(writer));
parser.parse(mediawikiText); // <1>
return writer.toString();
}
----
<1> Main call of the Mylyn Wikitext framework
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Callout
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Callout – Copy paste friendly
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
code snippets corresponding to source code under control
− Always up-to-date
− Ease maintenance
Real source code in your documentation
== Usage of Mylyn wikitext
With the method `toHtml(String)` in <<lst-wikitext1>> you
can convert a text from Mediawiki Language to HTML.
[[lst-wikitext1, Listing 1]]
[source,java]
----
include::src/main/java/MediawikiTest.java[tags=method]
----
<1> Main call of the Mylyn Wikitext framework
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Real source code in your documentation
public class MediawikiTest {
//tag::method[]
public static String toHtml(String mediawikiText) {
StringWriter writer = new StringWriter();
MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), new HtmlDocumentBuilder(writer));
parser.parse(mediawikiText); // <1>
return writer.toString();
}
//end::method[]
@Test
public void test() {
StringBuilder sb = new StringBuilder();
sb.append("= Heading 1 =\n");
sb.append("\n");
sb.append("Hello World!\n");
sb.append("\n");
sb.append("* Lorem\n");
sb.append("* Ipsum\n");
sb.append("\n");
sb.append("This is '''Mediawiki''' language.\n");
String html = toHtml(sb.toString());
String expected = "<h1 id=\"Heading_1\">Heading 1</h1><p>Hello World!</p><ul><li>Lorem</li><li>Ipsum</li></ul><p>This is
<b>Mediawiki</b> language.</p>";
assertTrue("epexted HTML not found in the output", html.contains(expected));
}
}
§
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Text: Calibri, Fett, 42
Single source your documents
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Text: Calibri, Fett, 52
Special: « Alt+0171 » Alt+0187
«AsciiDoc lets me do variable substitution and conditional inclusion»
Wayne Beaton, Eclipse Foundation https://waynebeaton.wordpress.com/2015/08/10/new-eclipse-project-handbook/
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
One source, multiple output
Eclipse Fundation Handbook
LocationTech Handbook
PolarSys Handbook
…
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Variable substitution
Open source projects at the Eclipse Foundation are required
to make use of certain Eclipse Foundation services:
* All project issues must be tracked in the
{bugzillaUrl}[{forgeName} Bugzilla]instance;
:forgeName: Eclipse
:bugzillaUrl: https://bugs.eclipse.org/bugs
Eclipse Project Handbook
========================
include::chapters/resources.adoc[] eclipse.adoc
resources.adoc
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Variable substitution
Open source projects at the Eclipse Foundation are required
to make use of certain Eclipse Foundation services:
* All project issues must be tracked in the
{bugzillaUrl}[{forgeName} Bugzilla]instance;
:forgeName: LocationTech
:bugzillaUrl: https://www.locationtech.org/bugs
LocationTech Project Handbook
=============================
include::chapters/resources.adoc[] locationtech.adoc
resources.adoc
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Conditional inclusion
ifeval::["{forgeName}"=="Eclipse"]
_The Eclipse Foundation strongly encourages all projects to
create an
maintain and http://marketplace.eclipse.org[Eclipse
Marketplace]
presence._
endif::[]
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Text: Calibri, Fett, 42
Simple Tools (no setup)
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Any text editor
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Extension for Chrome: Asciidoctor.js Live Preview
Live preview in Chrome
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
JavaFX Codeeditors – Tom Schindl
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Text: Calibri, Fett, 42
Build
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Text: Calibri, Fett, 52
Special: « Alt+0171 » Alt+0187
«Generating the documentation with Asciidoctor is always a straightforward experience»
Julien Ponge, Eclipse Golo project https://julien.ponge.org/blog/an-experiment-in-maven-to-gradle-migration/
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Ruby, JavaScript, JVM environments
Integration with a lot of build systems:
− Maven
− Gradle
Dependencies available in several repositories
− Maven central
− JCenter
− NPM
You can build on every machine, without a complex setup
Build system
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Text: Calibri, Fett, 42
Edit on GitHub
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
Edit on GitHub
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
GitHub Editor
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: 2. Zeile als Untertitel nicht Fett
GitHub Preview
Farben:
254/153/21
0/130/161
127/127/127
Schrift: Titel: Calibri, Fett, 32
Text: Calibri, 22 (mind. 18)
Special: Automatischer Einzug
Eclipse Scout 2015
Thanks
/@j2r2b /+JeremieBresson
/jmini jeremie.bresson@bsi-software.com
top related