Il semble que j'ai dû faire des dizaines de présentations pour mes collègues, des clients et des interventions publiques durant ma carrière dans l'IT. Pendant de nombreuses années, Powerpoint est resté pour moi le choix naturel et fiable pour la création de diapos. Mais cette année, la situation a changé de manière significative. De février à mai, j'ai eu l'occasion de parler lors de cinq conférences, et il fallait préparer les diapositives rapidement mais de manière qualitative. La question de déléguer le travail de design visuel des diapositives à d'autres personnes s'est alors posée. Une fois, j'ai tenté de travailler avec un designer en envoyant des fichiers .pptx par mail, mais cela s'est transformé en chaos : personne ne savait quelle version des diapositives était « la plus récente », et la mise en page était affectée par les différences de versions de Powerpoint et de polices sur nos machines. J'ai donc décidé d'essayer quelque chose de nouveau. J'ai essayé, et depuis, je ne pense pas revenir à Powerpoint.
Ce que nous voulons
Il y a environ un an et demi, nous avons abandonné l'utilisation de Word pour créer la documentation de projet, rencontrant les mêmes problèmes : bien que Word soit bon pour rédiger un petit document, à mesure que le volume augmente, des difficultés apparaissent pour le travail collaboratif et pour obtenir une mise en page saine et unifiée. Notre choix s'est porté sur , et nous ne cessons d'en être ravis, mais c'est un sujet pour un autre article. À peu près à ce moment-là, nous avons découvert l'efficacité d'un des principes DevOps « everything as code », donc le choix des exigences pour la nouvelle technologie de création de diapositives était assez évident :
- La présentation doit être un fichier texte brut en langage de balisage.
- Nos diapositives portent sur des projets de développement, donc le balisage doit permettre d'insérer facilement, sans avoir besoin de systèmes externes,
- des extraits de code avec coloration syntaxique,
- des diagrammes simples sous forme de figures géométriques reliées par des flèches,
- des diagrammes UML, des organigrammes et autres.
- Le projet de présentation doit être stocké dans un système de contrôle de version.
- La validation et la compilation des diapositives finales doivent être effectuées dans un système CI.
À ce jour, il existe deux options de base pour créer des diapositives dans les langages de balisage : le paquet pour LaTeX ou l'un des frameworks pour créer des diapositives en HTML/CSS (, , et bien d'autres).
Bien que mon cœur penche pour LaTeX, mon esprit me disait que le choix de la solution, que je n'utiliserais pas seul, devait être en faveur d'une solution connue d'un public plus large. LaTeX n'est pas compris par tous, et si votre pratique quotidienne n'est pas liée à la rédaction d'articles scientifiques, il est peu probable que vous ayez le temps de plonger dans le vaste et complexe monde de ce système.
Cependant, la maîtrise de HTML/CSS n'est pas un talent universel : je ne le maîtrise pas entièrement, par exemple. Heureusement, AsciiDoctor, déjà connu de nous, vient à la rescousse : un convertisseur permet de créer des diapositives RevealJS en utilisant la mise en page AsciiDoctor. Et celle-ci est facile à apprendre et accessible à tous !
Comment coder les diapositives
Pour comprendre l'essence du codage de diapositives sur AsciiDoctor, il est plus simple d'apporter des exemples concrets. Tous proviennent de vraies diapositives que j'ai créées pour mes présentations en conférence cette année.
Une diapositive avec un titre et une liste d'éléments déroulants :
== Pourquoi avons-nous besoin de l'API Streams ?
[%step]
* Traitement de flux en temps réel
* API de type flux (map / reduce)
* En coulisses :
** Engagement automatique des offsets
** Rééquilibrage
** État interne des traitements
** Scalabilité facileRésultat
Un titre et un extrait de code source avec surlignage syntaxique :
== Kafka Streams API : structure générale d'une application KStreams
[source,java]
----
StreamsConfig config = ...;
// Ici, nous définissons diverses options
Topology topology = new StreamsBuilder()
// Ici, nous construisons la topologie
....build();
----Résultat
Dans le processus de préparation de la présentation, les exemples de code de démonstration subissent de multiples modifications et améliorations, il est donc précieux de pouvoir copier et coller rapidement le "code brut" directement dans la diapositive, garantissant l'actualité de l'exemple de démonstration sans se soucier de la mise en évidence de la syntaxe.
Titre, illustration et texte (la mise en page dans la diapositive se fait dans les cellules ):
== Kafka Streams in Action
[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams in Action”, novembre 2018
* Exemples de code pour Kafka 1.0
|===Résultat
Parfois, un titre n'est pas nécessaire, et pour illustrer votre pensée, il suffit d'une image en plein écran :
[%notitle]
== Vivre dans un héritage n'est pas facile
image::swampman.jpg[canvas, size=cover]Résultat
Souvent, il est nécessaire de soutenir une idée par un simple diagramme sous la forme de « carrés reliés par des flèches ». Heureusement, AsciiDoctor est intégré à un système. — une langue permettant de décrire des diagrammes graphiques basés sur la description des nœuds et des liens entre eux. Il faut maîtriser Graphviz, mais il est assez facile de le faire en s'appuyant sur des exemples existants ! Voici à quoi cela ressemble :
== Création de l'application « Bet Totalling App »
Quel est le montant des paiements pour les paris effectués si l'issue se joue ?
[graphviz, "counting-topology.png"]
-----
digraph G {
graph [ dpi = 150 ];
rankdir="LR";
node [fontsize=18; shape="circle"; fixedsize="true"; width="1.1"];
Store [shape="cylinder"; label="Magasin Local"; fixedsize="true"; width="1.5"]
Source -> MapVal -> Sum -> Sink
Sum -> Store [dir=both; label=" n "]
{rank = same; Store; Sum;}
}
-----Résultat
Dans le cas où il serait nécessaire d'éditer l'étiquette de la figure, de changer la direction de la flèche, etc. — cela peut être fait directement dans le code de la présentation, au lieu de redessiner l'image ailleurs et de la réinsérer dans la diapositive. Cela augmente considérablement la rapidité de travail sur les diapositives.
Un exemple un peu plus complexe :
== Assemblage non reproductible
[graphviz, "unstable-update.png"]
-----
digraph G {
rankdir="LR";
graph [ dpi = 150 ];
u -> r0;
u[shape=plaintext; label="linter updaten+ 13 warnings"]
r0[shape=point, width = 0]
r1 -> r0[ arrowhead = none, label="branche master" ];
r0-> r2 []; b1 -> b4; r1->b1
r1[label="150nwarnings"]
b1[label="± 0nwarnings"]
b4[label="± 0nwarnings"]
b4->r2
r2[label="163nwarnings", color="red", xlabel=<fusion bloquée>]
{rank = same; u; r0; b4;}
}
-----Résultat
Au fait, expérimenter avec Graphviz et déboguer des images est pratique sur la page .
Enfin, si vous devez insérer dans une diapositive un organigramme, un diagramme de classes ou un autre diagramme standardisé, une autre solution intégrée à AsciiDoctor peut être utile, . Mon collègue Nikolay Potashnikov a écrit sur les vastes capacités de PlantUML .
Transformer un projet de présentation en code stocké dans un système de contrôle de version permet d'organiser un travail collaboratif sur la présentation, en particulier de diviser les tâches de création de contenu et de mise en forme. La présentation des diapositives (polices, arrière-plans, marges) dans RevealJS est décrite à l'aide de CSS. Mon habileté personnelle à travailler avec CSS se transmet le mieux par — mais ce n'est pas grave, car il y a des gens qui travaillent avec CSS beaucoup plus habilement et rapidement que moi. Au final, nous pouvons travailler simultanément sur différents fichiers via Git et augmenter la vitesse de collaboration, impossible lors de l'envoi de fichiers .pptx par e-mail.
Assemblage d'une page HTML avec des diapositives
Les fichiers source en texte brut, c'est bien, mais comment les compiler dans la présentation elle-même ?
AsciiDoctor est un projet écrit en Ruby, et il peut être lancé de plusieurs manières. D'abord, vous pouvez installer le langage Ruby et exécuter asciidoctor directement, ce qui sera probablement le plus proche des développeurs Ruby.
Si vous ne souhaitez pas vous occuper de l'installation de Ruby, vous pouvez utiliser l'image Docker , dans laquelle vous pouvez monter le dossier contenant les fichiers source du projet via VOLUME lors de son lancement et obtenir le résultat à l'emplacement désigné.
La solution sur laquelle j'ai choisi de m'arrêter peut sembler quelque peu inattendue, mais elle est la plus confortable pour moi en tant que développeur Java. Elle ne nécessite ni installation de Ruby, ni présence de Docker, mais permet de générer des diapositives à l'aide d'un script Maven.
En fait, le projet — une implémentation Java du langage Ruby — est si bon qu'il permet d'exécuter dans la machine Java presque tout ce qui a été créé pour Ruby, et le lancement d'AsciiDoctor en est l'une des applications les plus fréquentes de JRuby.
Présence permet de compiler la documentation AsciiDoctor qui fait partie d'un projet Java (ce dont nous profitons activement). Dans ce cas, AsciiDoctor et JRuby sont téléchargés automatiquement par Maven, et AsciiDoctor s'exécute dans l'environnement JRuby : rien à installer sur la machine ! (À l'exception du package graphviz, qui est nécessaire si vous souhaitez utiliser des graphiques GraphViz ou PlantUML.) Il suffit de placer vos fichiers .adoc dans le dossier src/main/asciidoc/. Voici , générant des diapositives avec des diagrammes.
Conversion des diapositives en PDF
Bien que la version HTML des diapositives soit tout à fait autonome, avoir une version PDF des diapositives est parfois nécessaire. D'abord, il arrive que dans certaines conférences, ne permettant pas au conférencier de brancher son propre ordinateur portable, on exige des diapositives « strictement au format pptx ou pdf », sans s'attendre à les voir en HTML. Deuxièmement, il est de bon ton d'envoyer aux organisateurs une version immuable de vos diapositives telles qu'elles ont été présentées lors du discours, au format PDF pour publication dans les documents de la conférence.
Heureusement, cette tâche est gérée par l'outil Node.js , basé sur — un système d'automatisation du contrôle du navigateur Chrome. Convertir une présentation RevealJS en PDF peut se faire avec la commande
node decktape.js -s 3200x1800 --slides 1-500
reveal "file:///index.html?fragments=true" slides.pdf Deux astuces lors du lancement de decktape que j'ai dû découvrir par essais et erreurs :
la résolution via un paramètre
-sIl faut définir avec une réserve double, sinon des problèmes peuvent survenir avec les résultats de la conversion.Dans l'URL de la version HTML de la présentation, le paramètre doit être transmis.
?fragments=true, ce qui permettra de créer une page PDF distincte pour chaque état intermédiaire de votre diapositive (par exemple, cinq pages pour cinq points de la liste, s'ils sont affichés un par un). Cela permettra d'utiliser ce PDF en tant que présentation lors d'une conférence.
Compilation et publication automatiques sur le web
Il est pratique que les diapositives soient automatiquement compilées lors de l'intégration des modifications dans le système de contrôle de version, et encore plus pratique lorsque les diapositives compilées automatiquement sont mises en ligne pour une utilisation générale. Les diapositives en ligne peuvent facilement être 'jouées' devant un public depuis n'importe quel appareil connecté à Internet et à un projecteur.
Comme nous utilisons GitHub dans notre travail, le choix naturel du système CI est , et pour l'hébergement des présentations prêtes — . L'idée de github.io est que tout contenu statique placé dans la branche gh-pages de votre projet sur GitHub devient accessible à l'adresse .gihub.io/.
Le fichier de configuration complet de TravisCI, incluant la compilation de la version HTML de la page via Maven, la conversion en PDF avec decktape et le téléchargement des résultats dans la branche gh-pages pour publication sur github.io, ressemble à .
Pour construire un tel projet côté TravisCI, il est nécessaire de configurer les variables d'environnement
GH_REF— une valeur du type github.com/inponomarev/csa-hbGH_TOKEN— le jeton d'accès à GitHub. Il peut être obtenu dans les paramètres de votre profil GitHub, dans Developer Settings -> Personal Access Tokens. Si vous publiez votre présentation dans un dépôt public, il suffit d'accorder à ce jeton un accès 'Access public repositories'.GH_USER_EMAIL/GH_USER_NAME— la paire nom/email, au nom de laquelle le push dans la branche sera effectué.gh-pages.
Ainsi, chaque commit du code de la présentation sur GitHub entraîne une reconstruction automatique des diapositives aux formats HTML et PDF et leur mise à jour sur github.io. (Bien sûr, il ne faut mettre sur github.io que les présentations que vous souhaitez rendre publiques à la fin.)
Exemples de projets
Enfin, voici des liens vers quelques exemples de projets de présentation avec des scripts Maven configurés et des configurations CI pour Travis-CI, que vous pouvez cloner et utiliser pour créer vos propres projets de présentation :
(ma présentation pour JPoint 2019)
(ma présentation pour Heisenbug 2019)
Adieu, PowerPoint ! Je ne pense pas que j'aurai un jour besoin de toi pour des présentations techniques 🙂
Source : habr.com
