with Asciidoctor Jrmie Bresson 03.11.2015 AsciiDoc AsciiDoc - - PowerPoint PPT Presentation

▶
with asciidoctor
SMART_READER_LITE
LIVE PREVIEW

with Asciidoctor Jrmie Bresson 03.11.2015 AsciiDoc AsciiDoc - - PowerPoint PPT Presentation

Dec 10, 2023 208 likes •611 views

Writing documentation with Asciidoctor Jrmie Bresson 03.11.2015 AsciiDoc AsciiDoc example = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application

slide-1
SLIDE 1

Jérémie Bresson – 03.11.2015

Writing documentation with Asciidoctor

slide-2
SLIDE 2

AsciiDoc

slide-3
SLIDE 3

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].

slide-4
SLIDE 4

AsciiDoc example

slide-5
SLIDE 5

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].

slide-6
SLIDE 6

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

slide-7
SLIDE 7

= 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

slide-8
SLIDE 8

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

slide-9
SLIDE 9

= 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

slide-10
SLIDE 10

= 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

slide-11
SLIDE 11

Asciidoctor

slide-12
SLIDE 12

 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

slide-13
SLIDE 13

Multiple Outputs

 PDF  HTML pages  Eclipse Help guides

slide-14
SLIDE 14

«Why is asciidoctor a great tool?»

slide-15
SLIDE 15

Source code listings

slide-16
SLIDE 16

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(), ne parser.parse(mediawikiText); return writer.toString(); }

slide-17
SLIDE 17

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(), ne parser.parse(mediawikiText); // <1> return writer.toString(); }

  • <1> Main call of the Mylyn Wikitext framework
slide-18
SLIDE 18

Callout

slide-19
SLIDE 19

Callout – Copy paste friendly

slide-20
SLIDE 20

 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
slide-21
SLIDE 21

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 HtmlDocume 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");

slide-22
SLIDE 22

Single source your documents

slide-23
SLIDE 23

«AsciiDoc lets me do variable substitution and conditional inclusion»

Wayne Beaton, Eclipse Foundation

https://waynebeaton.wordpress.com/2015/08/10/new-eclipse-project-handbook/

slide-24
SLIDE 24

One source, multiple output

Eclipse Fundation Handbook LocationTech Handbook PolarSys Handbook …

slide-25
SLIDE 25

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

slide-26
SLIDE 26

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

slide-27
SLIDE 27

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::[]

slide-28
SLIDE 28

Simple Tools (no setup)

slide-29
SLIDE 29

Any text editor

slide-30
SLIDE 30

 Extension for Chrome: Asciidoctor.js Live Preview

Live preview in Chrome

slide-31
SLIDE 31

JavaFX Codeeditors – Tom Schindl

slide-32
SLIDE 32

Build

slide-33
SLIDE 33

«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/

slide-34
SLIDE 34

 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

slide-35
SLIDE 35

Edit on GitHub

slide-36
SLIDE 36

Edit on GitHub

slide-37
SLIDE 37

GitHub Editor

slide-38
SLIDE 38

GitHub Preview

slide-39
SLIDE 39

Eclipse Scout 2015

Thanks

/@j2r2b /+JeremieBresson /jmini jeremie.bresson@bsi-software.com