Здаецца, мне давялося зрабіць дзясяткі прэзентацый для калег, замоўцаў і публічных выступаў за маю кар'еру ў IT. Шмат гадоў Powerpoint як сродак выраба слайдаў заставаўся для мяне натуральным і надзейным выбарам. Але сёлета сітуацыя якасна змянілася. З лютага па май мне давялося выступіць на пяці канферэнцыях, і слайды да дакладаў трэба было рыхтаваць у сціслыя тэрміны, але якасна. Паўстала пытанне аб дэлегаванні той часткі працы, што да візуальнага дызайну слайдаў, іншым людзям. Неяк раз я паспрабаваў працаваць з дызайнерам, перасылаючы файлы .pptx па пошце, але праца ператварылася ў хаос: ніхто не ведаў, якая версія слайдаў самая новая , а вёрстка ехала па чынніку адрознення версій Powerpoint і шрыфтоў на нашых машынах . І я вырашыў паспрабаваць нешта новае. Паспрабаваў, і з таго часу не думаю вяртацца да Powerpoint.
Што мы хочам
Гады паўтара таму мы ў кампаніі адмовіліся ад выкарыстання Word для стварэння праектнай дакументацыі, сутыкнуўшыся з тымі ж праблемамі: хоць Word добры для таго, каб набраць невялікі дакумент, па меры росту аб'ёмаў, узнікаюць цяжкасці з сумеснай працай і атрыманнем якаснага і ўніфікаванага афармлення. Наш выбар упаў на , і выбару гэтага мы не перастаем цешыцца, але гэта тэма для асобнага артыкула. Прыкладна тады ж мы спазналі эфектыўнасць аднаго з DevOps-прынцыпаў "everything as code", таму выбар патрабаванняў для новай тэхналогіі стварэння прэзентацыйных слайдаў быў даволі відавочным:
- Прэзентацыя павінна ўяўляць сабой plain text-файл на мове разметкі.
- Слайды ў нас пра праекты распрацоўкі, таму разметка павінна дазваляць лёгка, не звяртаючыся да дапамогі вонкавых сістэм, устаўляць
- фрагменты кода з падсветкай сінтаксісу,
- простыя дыяграмы ў выглядзе геаметрычных фігур, злучаных стрэлкамі,
- UML-дыяграмы, блок-схемы і іншае.
- Праект прэзентацыі павінен захоўвацца ў сістэме кантролю версій.
- Валідацыя і зборка гатовых слайдаў павінна рабіцца ў CI-сістэме.
На сёння магчымы два базавыя варыянты стварэння слайдаў на мовах разметкі: пакет для LaTeX або адзін з фрэймворкаў для стварэння слайдаў на HTML/CSS (, , і многія іншыя).
Хоць мая душа ляжыць да LaTeX-у, розум падказваў, што выбар рашэння, якім буду карыстацца не я адзін, павінен быць на боку рашэння, знаёмага шырэйшаму кругу твараў. LaTeX ведаюць не ўсё, і калі ваша штодзённая практыка не злучана з напісаннем навуковых артыкулаў, то ці наўрад у вас знойдзецца час на апусканне ў велізарны мудрагелісты свет гэтай сістэмы.
Зрэшты, і валоданне HTML/CSS – не сказаць каб паўсюдна распаўсюджаны навык: я, напрыклад, ім валодаю далёка не ў поўнай меры. На шчасце, тут на дапамогу прыходзіць ужо знаёмы нам AsciiDoctor: канвэртар. дазваляе ствараць RevealJS-слайды, выкарыстоўваючы AsciiDoctor-разметку. А ўжо яна простая для вывучэння і даступная кожнаму!
Як закадзіраваць слайды
Каб зразумець сутнасць кадавання слайдаў на AsciiDoctor, прасцей за ўсё прывесці канкрэтныя прыклады. Усе яны - з рэальных слайдаў, якія я рабіў для сваіх канферэнцыйных дакладаў у гэтым годзе.
Слайд з загалоўкам і спісам у адкрываных адзін за адным пунктах:
== Зачем нам Streams API?
[%step]
* Real-time stream processing
* Stream-like API (map / reduce)
* Под капотом:
** Автоматический offset commit
** Ребалансировка
** Внутреннее состояние обработчиков
** Легкое масштабированиеВынік
Загаловак і фрагмент зыходнага кода з падсветкай сінтаксісу:
== Kafka Streams API: общая структура KStreams-приложения
[source,java]
----
StreamsConfig config = ...;
//Здесь устанавливаем всякие опции
Topology topology = new StreamsBuilder()
//Здесь строим топологию
....build();
----Вынік
У працэсе падрыхтоўкі да дакладу дэманстрацыйныя прыклады кода падвяргаюцца неаднаразовым пераробкам і паляпшэнням, таму бясцэнная магчымасць хутка скапіяваць і ўставіць "волкі код" прама ў слайд, забяспечваючы актуальнасць дэма-прыкладу і не клапоцячыся аб падсвятленні сінтаксісу.
Загаловак, ілюстрацыя і тэкст (раскладку па слайдзе выконваем у ячэйках ):
== Kafka Streams in Action
[.custom-style]
[cols="30a,70a"]
|===
|image::KSIA.jpg[]
|
* **William Bejeck**, +
“Kafka Streams in Action”, November 2018
* Примеры кода для Kafka 1.0
|===Вынік
Часам загаловак не патрэбен, а для ілюстрацыі тваёй думкі патрэбна проста карцінка ва ўвесь экран:
[%notitle]
== Жить в легаси нелегко
image::swampman.jpg[canvas, size=cover]Вынік
Часта думку неабходна падмацаваць простай дыяграмай, у выглядзе «квадрацікаў, злучаных стрэлачкамі». На шчасце, AsciiDoctor інтэграваны з сістэмай - мовай, якая дазваляе апісваць графавыя дыяграмы на падставе апісання вяршыняў і сувязяў паміж імі. Graphviz трэба асвойваць, але на аснове наяўных прыкладаў зрабіць гэта даволі лёгка! Вось як гэта выглядае:
== Пишем “Bet Totalling App”
Какова сумма выплат по сделанным ставкам, если сыграет исход?
[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="Local Store"; fixedsize="true"; width="1.5"]
Source -> MapVal -> Sum -> Sink
Sum -> Store [dir=both; label=" n "]
{rank = same; Store; Sum;}
}
-----Вынік
У выпадку, калі неабходна адрэдагаваць подпіс на постаці, змяніць кірунак стрэлкі і т. п. - гэта можна зрабіць непасрэдна ў кодзе прэзентацыі, замест таго, каб перамалёўваць дзесьці карцінку і зноўку ўстаўляць яе ў слайд. Гэта значна павялічвае хуткасць працы над слайдамі.
Прыклад складаней:
== Невоспроизводимая сборка
[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="master branch" ];
r0-> r2 []; b1 -> b4; r1->b1
r1[label="150nwarnings"]
b1[label="± 0nwarnings"]
b4[label="± 0nwarnings"]
b4->r2
r2[label="163nwarnings", color="red", xlabel=<<font color="red">merge blocked</font>>]
{rank = same; u; r0; b4;}
}
-----Вынік
Дарэчы, эксперыментаваць з Graphviz і адладжваць карцінкі зручна на старонцы .
Нарэшце, калі трэба ўставіць у слайд блок-схему, дыяграму класаў ці іншую стандартызаваную дыяграму, то ў гэтым выпадку на дапамогу можа прыйсці яшчэ адна інтэграваная з AsciiDoctor сістэма, . Пра шырокія магчымасці PlantUML мой калега Мікалай Паташнікаў напісаў .
Ператварэнне праекта прэзентацыі ў код, які захоўваецца на сістэме кантролю версій, дае магчымасць арганізаваць сумесную працу над прэзентацыяй, перш за ўсё падзяліць задачы стварэння кантэнту і афармлення. Афармленне слайдаў (шрыфты, фоны, водступы) у RevealJS апісваецца з дапамогай CSS. Маё асабістае ўменне кіравацца з CSS лепш за ўсё перадае - але гэта не страшна, калі ёсць людзі, якія працуюць з CSS значна спрытней і хутчэй за мяне. У выніку атрымліваецца, што ва ўмовах імкліва надыходзячага дэдлайну па прэзентацыі мы можам працаваць адначасова над рознымі файламі праз Git і развіваць хуткасць сумеснай працы, немагчымую пры перасылцы па пошце файлаў .pptx.
Зборка HTML-старонкі са слайдамі
Plain text-зыходнікі - гэта выдатна, але як іх скампіляваць у саму прэзентацыю?
AsciiDoctor - гэта праект, напісаны на Ruby, і запусціць яго можна некалькімі спосабамі. Па-першае, вы можаце ўсталяваць мову Ruby і запускаць asciidoctor напроста, што, мусіць, будзе найболей блізка Ruby-распрацоўнікам.
Калі не жадаецца звязвацца з усталёўкай Ruby, можна скарыстацца docker-выявай , у які пры запуску можна праз VOLUME падлучыць тэчку з зыходнікамі праекту і ў зададзеным месцы атрымаць вынік.
Варыянт, на якім спыніўся я, можа здацца некалькі нечаканым, але ён найболей зручны мне як Java-распрацоўніку. Ён не патрабуе ні ўсталёўкі Ruby, ні наяўнасці docker, затое дазваляе генераваць слайды з дапамогай Maven-скрыпту.
Справа ў тым, што праект - Java-рэалізацыя мовы Ruby - настолькі добры, што дазваляе запускаць у Java-машыне практычна ўсё, што створана для Ruby, і запуск AsciiDoctor - адно з найбольш частых ужыванняў JRuby.
наяўнасць дазваляе збіраць AsciiDoctor-дакументацыю, якая з'яўляецца часткай Java-праекта (чым мы актыўна карыстаемся). Пры гэтым AsciiDoctor і JRuby спампоўваюцца Maven-ым аўтаматычна, і AsciiDoctor выконваецца ў асяроддзі JRuby: нічога ўсталёўваць на машыну не трэба! (За выключэннем пакета graphviz, які патрэбен, калі вы хочаце выкарыстоўваць графіку GraphViz або PlantUML.) Дастаткова змясціць вашыя .adoc-файлы ў тэчку src/main/asciidoc/. Вось , які збірае слайды з дыяграмамі.
Канвертаванне слайдаў у PDF
Хоць HTML-версія слайдаў суцэль самадастатковая, усё ж мець PDF-варыянт слайдаў таксама бывае неабходна. Па-першае, здараецца, што на некаторых канферэнцыях, якія не даюць спікеру магчымасць падключэння ўласнага ноўтбука, патрабуюць слайды "строга ў фармаце pptx або pdf", не чакаючы, што яны бываюць яшчэ і ў HTML. Па-другое, добрым тонам з'яўляецца адправіць арганізатарам нязменны варыянт вашых слайдаў у тым выглядзе, як яны былі паказаны на дакладзе, у фармаце PDF для публікацыі файла ў матэрыялах канферэнцыі.
На шчасце, з гэтай задачай спраўляецца Node.js утыліта , пабудаваная на базе - сістэмы аўтаматызацыі кіравання браўзэрам Chrome. Канвертаваць RevealJS прэзентацыю ў PDF можна камандай
node decktape.js -s 3200x1800 --slides 1-500
reveal "file:///index.html?fragments=true" slides.pdf Дзве хітрасці пры запуску decktape, да якіх прыйшлося прыйсці метадам спроб і памылак:
-
дазвол праз параметр
-sтрэба задаваць з двухразовым запасам, інакш магчымыя праблемы з вынікамі канвертацыі. -
у URL HTML-версіі прэзентацыі трэба перадаваць параметр
?fragments=true, што дазволіць ствараць асобную PDF- старонку для кожнага прамежкавага стану вашага слайда (напрыклад, пяць старонак для пяці пунктаў спісу, калі яны паказваюцца адна за адной). Гэта дазволіць выкарыстоўваць такі PDF сам па сабе ў якасці прэзентацыі пры дакладзе.
Аўтаматычная зборка і публікацыя ў інтэрнэце
Зручна, калі слайды збіраюцца аўтаматычна пры трапленні змен у сістэму кантролю версій, і яшчэ зручней, калі аўтаматычна скампіляваныя слайды выкладваюцца ў інтэрнэт для ўсеагульнага выкарыстання. Слайды з інтэрнэту можна лёгка "прайграць" перад аўдыторыяй з любой машыны, падлучанай да інтэрнэту і праектару.
Т. к. мы выкарыстоўваем у працы GitHub, то натуральным выбарам CI-сістэмы з'яўляецца , а для хостынгу гатовых прэзентацый — . Ідэя github.io заключаецца ў тым, што любы статычны кантэнт, змешчаны ў галінку gh-pages вашага праекта на GitHub, становіцца даступны па адрасе <ваше имя>.gihub.io/<ваш проект>.
Поўны канфігурацыйны файл TravisCI, улучальны ў сябе кампіляцыю HTML-версіі старонкі з дапамогай Maven, канвертаванне ў PDF пры дапамозе decktape і выгрузку вынікаў у галінку gh-pages для публікацыі на github.io, выглядае .
Для зборкі такога праекта на боку TravisCI неабходна наладзіць зменныя асяроддзі
GH_REF- значэнне выгляду github.com/inponomarev/csa-hbGH_TOKEN- токен доступу да GitHub. Можна атрымаць у GitHub-е ў наладах свайго профіля, Developer Settings -> Personal Access Tokens. Калі вы выкладваеце прэзентацыю ў публічны рэпазітар, то для гэтага токена досыць паказаць адзіны ўзровень доступу "Access public repositories".GH_USER_EMAIL/GH_USER_NAME- пара імя/пошта, ад імя якой будзе ажыццёўлены пуш у галінкуgh-pages.
Такім чынам, кожны коміт кода прэзентацыі на GitHub прыводзіць да аўтаматычнага перастраення слайдаў у фарматах HTML і PDF і перазаліванні іх на github.io. (Вядома ж, выкладваць на github.io трэба толькі тыя прэзентацыі, якія вы хочаце ў выніку зрабіць публічнымі.)
Прыклады праектаў
Напрыканцы - спасылкі на пару прыкладаў праектаў прэзентацый з настроенымі Maven-скрыптамі і CI-канфігурацыяй для Travis-CI, якія можна кланаваць і выкарыстоўваць пры стварэнні ўласных праектаў прэзентацый:
-
(мой даклад для JPoint 2019)
-
(мой даклад для Heisenbug 2019)
Бывай, Powerpoint! Не думаю, што ты мне калі-небудзь спатрэбішся для тэхнічных прэзентацый 🙂
Крыніца: habr.com