Asciidoctor

Benoit Prioux
benoit.prioux@gmail.com
bdx io

Me

avatar

@binout
https://github.com/binout

  • Développeur Java depuis presque 10 ans
lectra
  • Technical Leader chez Lectra, numéro un mondial des solutions dédiées à l’industrie du textile (machines et logiciels)
bordeauxjug
  • Membre du Bordeaux JUG

Une solution : Asciidoc

asciidoc

Langage de balisage, créé en 2002 avec un processeur en Python

Parce que :

  • on se concentre plus sur le fond que sur la forme
  • c’est du texte, donc un éditeur classique suffit
  • on peut gérer l’historique avec un SCM
  • à partir d’une même source, on peut publier vers plusieurs formats
  • on a un peu l’impression de hacker ;-)

Exemple

= Hello, Bdx.io !
Benoit Prioux <benoit.prioux@gmail.com>

Introduction à http://asciidoc.org[AsciiDoc].

== Première Section

* foo
* bar

== Deuxième Section

1. item 1
2. item 2

NOTE: C'est l'heure de la démo !

Asciidoctor

dan-allen

https://github.com/asciidoctor

  • Implémentation open-source écrite en Ruby
  • Permet de convertir des fichiers asciidoc vers différents backends : docbook, html5, epub, pdf et même deckjs !

  • 12 août 2014 : sortie de la version 1.5.0

    • 1ère version majeure après 2 ans de développement
    • 50 contributeurs, 1800 commits, 1500 tests

Ils utilisent déjà asciidoctor

Asciidoctor est extensible …​

asciidoctor-diagram

asciiart

Diagram

asciidoctor-diagram et UML

class-diagram

Diagram

sequence-diagram

Diagram

Asciidoctor et les développeurs

Je suis développeur Ruby

Installation
gem install asciidoctor
CLI
$ asciidoctor -D output README.adoc
Ruby API
require 'asciidoctor'
...
Asciidoctor.convert_file 'README.adoc', to_file: true, safe: 'safe'

Je suis développeur Java

jruby

asciidoctorj

Asciidoctorj

https://github.com/asciidoctor/asciidoctorj
Asciidoctor asciidoctor = Asciidoctor.Factory.create();

Options options = options().backend("html5").get();
String rendered = asciidoctor.convert("*Gras* ou _italique_ ?", options);

System.out.println(rendered);
Console
<div class="paragraph">
<p><strong>Gras</strong> ou <em>italique</em> ?</p>
</div>

Asciidoctor Maven Plugin

https://github.com/asciidoctor/asciidoctor-maven-plugin
<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <version>1.5.0</version>
  <executions>
    <execution>
      <id>output-html</id>
      <phase>generate-resources</phase>
      <goals>
        <goal>process-asciidoc</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Asciidoctor Gradle Plugin

https://github.com/asciidoctor/asciidoctor-gradle-plugin
buildscript {
    repositories {
      jcenter()
    }

    dependencies {
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.0'
    }
}

apply plugin: 'org.asciidoctor.gradle.asciidoctor'

Asciidoctor Ant Task

https://github.com/asciidoctor/asciidoctor-ant
<project xmlns:asciidoctor="antlib:org.asciidoctor.ant">
...
    <target name="doc">
        <taskdef uri="antlib:org.asciidoctor.ant"
                 resource="org/asciidoctor/ant/antlib.xml"
                 classpath="lib/asciidoctor-ant-1.5.0.jar"/>

        <asciidoctor:convert sourceDirectory="src/asciidoc" outputDirectory="target"/>
    </target>
...
</project>

Asciidoclet

javadoc

https://github.com/asciidoctor/asciidoclet
/**
 * This class has the following features:
 *
 * - Support for *foo*
 * - Support for bar
 */
public class Thing implements Something { ... }

Je suis développeur Javascript

opal

asciidoctorjs

Asciidoctor.js

https://github.com/asciidoctor/asciidoctor.js
var content = "http://asciidoctor.org[*Asciidoctor*] " +
    "running on http://opalrb.org[_Opal_] " +
    "brings AsciiDoc to the browser!";

var options = Opal.hash2(['doctype', 'attributes'], {doctype: 'inline', attributes: ['showtitle']});

var html = Opal.Asciidoctor.$convert(asciidoc, options);

console.log(html);

Asciidoctor.js et Chrome

asciidoctor-chrome

← →

/