TOC

Introduction à Asciidoctor en Java

Introduction à Asciidoctor en Java

1. introduction

Dans cet article, nous allons faire une brève introduction sur l'utilisation d'Asciidoctor avec Java. Nous allons montrer comment générer du HTML5 ou un PDF à partir d'un document AsciiDoc.

2. Qu'est-ce qu'AsciiDoc?

AsciiDoc est un format de document texte. Il peut être utilisé pourwriting documentation, books, web pages, man pages and many other.

Comme il est très configurable, les documents AsciiDoc peuvent être convertis dans de nombreux autres formats tels que HTML, PDF, pages de manuel, EPUB et autres.

Comme la syntaxe AsciiDoc est assez basique, elle est devenue très populaire avec un support important dans divers plugins de navigateur, plugins pour langages de programmation et autres outils.

Pour en savoir plus sur l'outil, nous vous suggérons de lire lesofficial documentation où vous pouvez trouver de nombreuses ressources utiles pour apprendre la syntaxe et les méthodes appropriées pour exporter votre document AsciiDoc vers d'autres formats.

3. Qu'est-ce que Asciidoctor?

Asciidoctor est untext processor for converting AsciiDoc documents en HTML, PDF et autres formats. Il est écrit en Ruby et conditionné en RubyGem.

Comme mentionné ci-dessus, AsciiDoc est un format très populaire pour la rédaction de documentation. Vous pouvez donc facilement trouver Asciidoctor en tant que paquet standard dans de nombreuses distributions GNU Linux telles qu'Ubuntu, Debian, Fedora et Arch.

Puisque nous voulons utiliser Asciidoctor sur la JVM, nous parlerons d'AsciidoctorJ - qui est Asciidoctor avec Java.

4. Les dépendances

Pour inclure le package AsciidoctorJ dans notre application, l'entréepom.xml suivante est nécessaire: 


    org.asciidoctor
    asciidoctorj
    1.5.5


    org.asciidoctor
    asciidoctorj-pdf
    1.5.0-alpha.15

Les dernières versions des bibliothèques peuvent être trouvéeshere ethere.

5. API AsciidoctorJ

Le point d'entrée d'AsciidoctorJ est l'interface Java deAsciidoctor.

Ces méthodes sont:

  • convert - analyse le document AsciiDoc à partir d'unString ouStream et le convertit dans le type de format fourni

  • convertFile - analyse le document AsciiDoc à partir d'un objetFile fourni et le convertit dans le type de format fourni

  • convertFiles - identique à la précédente, mais la méthode accepte plusieurs objetsFile

  • convertDirectory - analyse tous les documents AsciiDoc dans le dossier fourni et les convertit dans le type de format fourni

5.1. Utilisation de l'API dans le code

Pour créer une instanceAsciidoctor, vous devez récupérer l'instance à partir de la méthode de fabrique fournie: 

import static org.asciidoctor.Asciidoctor.Factory.create;
import org.asciidoctor.Asciidoctor;
..
//some code
..
Asciidoctor asciidoctor = create();

Avec instance récupérée, nous pouvons convertir très facilement un document AsciiDoc: 

String output = asciidoctor
  .convert("Hello _example_!", new HashMap());

Si nous voulons convertir un document texte à partir du système de fichiers, nous utiliserons la méthodeconvertFile: 

String output = asciidoctor
  .convertFile(new File("example.adoc"), new HashMap());

Pour la conversion de plusieurs fichiers, la méthodeconvertFiles accepte l'objetList comme premier paramètre et renvoie des tableaux d'objetsString. Plus intéressant est de savoir comment convertir un répertoire entier avec AsciidoctorJ.

Comme mentionné ci-dessus, pour convertir un répertoire entier - nous devrions appeler la méthodeconvertDirectory. Cela analyse le chemin fourni et recherche tous les fichiers avec les extensions AsciiDoc (.adoc, .ad, .asciidoc, .asc) et les convertit. Pour analyser tous les fichiers, une instance desDirectoryWalker doit être fournie à la méthode.

Actuellement, Asciidoctor fournit deux implémentations intégrées de l’interface mentionnée:

  • AsciiDocDirectoryWalker - convertit tous les fichiers d'un dossier donné et de ses sous-dossiers. Ignore tous les fichiers commençant par «_»

  • GlobDirectoryWalker - convertit tous les fichiers d'un dossier donné suivant une expression glob 

String[] result = asciidoctor.convertDirectory(
  new AsciiDocDirectoryWalker("src/asciidoc"),
  new HashMap());

De plus, l'interfacewe can call convert method with provided java.io.Reader and java.io.Writer interfaces.Reader est utilisée comme source, et l'interfaceWriter est utilisée pour écrire les données converties: 

FileReader reader = new FileReader(new File("sample.adoc"));
StringWriter writer = new StringWriter();

asciidoctor.convert(reader, writer, options().asMap());

StringBuffer htmlBuffer = writer.getBuffer();

5.2. Génération de PDF

To generate a PDF file from an Asciidoc document, we need to specify the type of the generated file in options. Si vous regardez un peu plus attentivement les exemples précédents, vous remarquerez que le deuxième paramètre de toute méthode de conversion est unMap - qui représente un objet d'options.

Nous allons définir l'option in_place sur true afin que notre fichier soit automatiquement généré et enregistré dans le système de fichiers: 

Map options = options()
  .inPlace(true)
  .backend("pdf")
  .asMap();

String outfile = asciidoctor.convertFile(new File("example.adoc"), options);

6. Plugin Maven

Dans la section précédente, nous avons montré comment générer un fichier PDF directement avec votre propre implémentation en Java. Dans cette section, nous montrerons comment générer un fichier PDF lors de la construction de Maven. Simiar plugins exist for Gradle and Ant.

Pour activer la génération PDF pendant la construction, vous devez ajouter cette dépendance à vospom.xml: 


    org.asciidoctor
    asciidoctor-maven-plugin
    1.5.5
    
        
            org.asciidoctor
            asciidoctorj-pdf
            1.5.0-alpha.15

La dernière version de la dépendance du plugin Maven peut être trouvéehere.

6.1. Usage

Pour utiliser le plugin dans la construction, vous devez le définir dans lepom.xml: 


    
        
            output-html
            generate-resources
            
                process-asciidoc

Étant donné que le plug-in ne s’exécute pas dans une phase spécifique, vous devez définir la phase à laquelle vous souhaitez le démarrer.

Comme avec le plugin Asciidoctorj, nous pouvons également utiliser diverses options pour la génération de PDF.

Jetons un coup d'œil aux options de base pendant que vous pouvez trouver d'autres options dans lesdocumentation:

  • sourceDirectory - l'emplacement du répertoire où vous avez des documents Asciidoc

  • outputDirectory - l'emplacement du répertoire dans lequel vous souhaitez stocker les fichiers PDF générés

  • backend - le type de sortie d'Asciidoctor. Pour la génération de PDF définie pour le pdf

Voici un exemple comment définir les options de base dans le plugin: 


    
        src/main/doc
        target/docs
        pdf

Après avoir exécuté la construction, les fichiers PDF se trouvent dans le répertoire de sortie spécifié.

7. Conclusion

Même si AsciiDoc est très facile à utiliser et à comprendre, c'est un outil très puissant pour gérer la documentation et d'autres documents.

Dans cet article, nous avons présenté un moyen simple de générer des fichiers HTML et PDF à partir d'un document AsciiDoc.

Le code peut être trouvé surover on GitHub.

Related