🥇Ներկայացում կոդի տեսքով, կամ ինչու ես այլևս չեմ օգտագործում PowerPoint

Կարծում եմ՝ ՏՏ ոլորտում իմ կարիերայի ընթացքում տասնյակ շնորհանդեսներ եմ արել գործընկերների, հաճախորդների և հրապարակային ելույթների համար։ Տարիներ շարունակ PowerPoint-ը ինձ համար բնական և հուսալի ընտրություն էր որպես սլայդ պատրաստող։ Սակայն այս տարի իրավիճակը կտրուկ փոխվեց։ Փետրվարից մայիս ամիսներին ես պետք է ելույթ ունենայի հինգ կոնֆերանսներում, և շնորհանդեսների սլայդները պետք է պատրաստվեին կարճ ժամանակում, բայց բարձր որակով։ Հարց առաջացավ աշխատանքի այն մասը, որը վերաբերում է սլայդների տեսողական դիզայնին, հանձնարարել այլ մարդկանց։ Մի անգամ փորձեցի աշխատել դիզայների հետ՝ էլեկտրոնային փոստով ուղարկելով .pptx ֆայլեր, բայց աշխատանքը վերածվեց քաոսի. ոչ ոք չգիտեր, թե սլայդների որ տարբերակն է «ամենաթարմը», և դասավորությունը «գնաց» մեր մեքենաների PowerPoint տարբերակների և տառատեսակների տարբերությունների պատճառով։ Այսպիսով, որոշեցի փորձել ինչ-որ նոր բան։ Ես փորձեցի դա, և այդ ժամանակից ի վեր չեմ մտածել PowerPoint-ին վերադառնալու մասին։

Ինչ ենք մենք ուզում

Մոտ մեկուկես տարի առաջ մենք՝ ընկերությունում, հրաժարվեցինք Word-ի օգտագործումից նախագծային փաստաթղթեր ստեղծելու համար՝ բախվելով նույն խնդիրներին. չնայած Word-ը լավ է փոքր փաստաթուղթ մուտքագրելու համար, ծավալի աճին զուգընթաց դժվարություններ են առաջանում համագործակցության և բարձրորակ ու միասնական դիզայն ստանալու հետ կապված: Մեր ընտրությունը կանգ առավ... AsciiDoctor, և մենք երբեք չենք դադարում ուրախանալ այս ընտրությունից, բայց սա առանձին հոդվածի թեմա է։ Մոտավորապես նույն ժամանակահատվածում մենք իմացանք DevOps սկզբունքներից մեկի՝ «ամեն ինչ որպես կոդ» սկզբունքի արդյունավետության մասին, ուստի շնորհանդեսների սլայդներ ստեղծելու նոր տեխնոլոգիայի պահանջների ընտրությունը բավականին ակնհայտ էր.

Ներկայացումը պետք է լինի պարզ տեքստային ֆայլ՝ նշագրման լեզվով։
Մեր սլայդները վերաբերում են մշակման նախագծերին, ուստի նշագրումը պետք է թույլ տա հեշտ ներմուծում առանց արտաքին համակարգերի օգնության։
- կոդի հատվածներ՝ շարահյուսական ընդգծմամբ,
- պարզ դիագրամներ՝ երկրաչափական ձևերի տեսքով, որոնք միացված են նետերով,
- UML դիագրամներ, հոսքային դիագրամներ և այլն:
Ներկայացման նախագիծը պետք է պահվի տարբերակների կառավարման համակարգում։
Ավարտված սլայդների վավերացումը և հավաքումը պետք է իրականացվի CI համակարգում։

Այսօր նշագրման լեզուներով սլայդներ ստեղծելու երկու հիմնական տարբերակ կա՝ փաթեթ պրոյեկտոր LaTeX-ի կամ HTML/CSS սլայդների ստեղծման շրջանակներից մեկի համար (RevealJS, մեկնաբանություն, deck.js և շատ ուրիշներ):

Չնայած իմ սիրտը LaTeX-ի մեջ է, միտքս ինձ ասում էր, որ այնպիսի լուծման ընտրությունը, որը ես միակը չէի լինի, պետք է լինի ավելի լայն շրջանակի համար ծանոթ լուծման կողմը։ Ոչ բոլորն են ծանոթ LaTeX-ին, և եթե ձեր ամենօրյա պրակտիկան կապված չէ գիտական հոդվածներ գրելու հետ, ապա քիչ հավանական է, որ դուք ժամանակ կգտնեք ընկղմվելու այս համակարգի հսկայական և բարդ աշխարհում։

Սակայն HTML/CSS-ի տիրապետումը համընդհանուր տարածված հմտություն չէ. ես, օրինակ, հեռու եմ դրանից լիովին տիրապետելուց։ Բարեբախտաբար, այստեղ օգնության է հասնում արդեն ծանոթ AsciiDoctor-ը՝ փոխարկիչը։ asciidoctor-revealjs թույլ է տալիս ստեղծել 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();
----

Արդյունք

Զեկույցի նախապատրաստման ընթացքում դեմո կոդի օրինակները ենթակա են բազմիցս վերանայումների և բարելավումների, ուստի անգնահատելի է «հում կոդը» սլայդի մեջ արագ պատճենելու և տեղադրելու հնարավորությունը, որը կապահովի, որ դեմո օրինակը թարմացված լինի և չմտածի շարահյուսական ընդգծման մասին։

Վերնագիր, նկարազարդում և տեքստ (սլայդի վրա դասավորությունը կատարվում է բջիջներով) AsciiDoctor աղյուսակներ):

== 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Իմ գործընկեր Նիկոլայ Պոտաշնիկովը գրել է PlantUML-ի լայն հնարավորությունների մասին։ առանձին գրառում.

Ներկայացման նախագիծը տարբերակների կառավարման համակարգում պահված կոդի վերածելը հնարավորություն է տալիս կազմակերպել համագործակցություն ներկայացման վրա՝ հիմնականում առանձնացնելով բովանդակության ստեղծման և դիզայնի առաջադրանքները: RevealJS-ում սլայդների դիզայնը (տառատեսակներ, ֆոններ, խորշեր) նկարագրվում է CSS-ի միջոցով: CSS-ի հետ իմ անձնական հմտությունները լավագույնս արտահայտվում են հետևյալ կերպ. այս gif-ը — բայց դա սարսափելի չէ, երբ կան մարդիկ, ովքեր CSS-ի հետ աշխատում են ինձանից շատ ավելի հմտորեն և արագ։ Արդյունքում, պարզվում է, որ ներկայացման արագ մոտեցող վերջնաժամկետի պայմաններում մենք կարող ենք Git-ի միջոցով միաժամանակ աշխատել տարբեր ֆայլերի վրա և զարգացնել համագործակցության այնպիսի արագություն, որն անհնար է .pptx ֆայլերը էլեկտրոնային փոստով ուղարկելիս։

HTML էջի կառուցում սլայդներով

Պարզ տեքստային աղբյուրները հիանալի են, բայց ինչպե՞ս դրանք համատեղել ներկայացման մեջ։

AsciiDoctor-ը Ruby նախագիծ է, և այն գործարկելու մի քանի եղանակ կա։ Նախ, դուք կարող եք տեղադրել Ruby լեզուն և անմիջապես գործարկել asciidoctor-ը, որը, հավանաբար, Ruby մշակողներին ամենից ծանոթն է։

Եթե չեք ուզում անհանգստանալ Ruby-ի տեղադրման համար, կարող եք օգտագործել docker-ի պատկերը։ ասցիիդոկտոր/դոկեր-ասցիիդոկտոր, որի գործարկման ժամանակ դուք կարող եք VOLUME-ի միջոցով միացնել թղթապանակը նախագծի աղբյուրների հետ և ստանալ արդյունքը նշված վայրում։

Ընտրածս տարբերակը կարող է մի փոքր անսպասելի թվալ, բայց որպես Java մշակող՝ ինձ համար ամենահարմարն է։ Այն չի պահանջում Ruby-ի կամ docker-ի առկայություն, բայց թույլ է տալիս ստեղծել սլայդներ Maven սկրիպտի միջոցով։

Բանն այն է, որ նախագիծը ՋՌուբի — Ruby լեզվի Java իրականացումն այնքան լավն է, որ թույլ է տալիս Java մեքենայի վրա գործարկել Ruby-ի համար ստեղծված գրեթե ամեն ինչ, իսկ AsciiDoctor-ի գործարկումը JRuby-ի ամենատարածված կիրառումներից մեկն է։

առկայություն asciidoctor-maven-plugin թույլ է տալիս ստեղծել 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 անհրաժեշտ է սահմանել կրկնակի պահուստով, հակառակ դեպքում կարող են խնդիրներ առաջանալ փոխակերպման արդյունքների հետ
Ներկայացման HTML տարբերակի URL-ում անհրաժեշտ է փոխանցել պարամետր ?fragments=true, որը թույլ կտա ձեզ ստեղծել առանձին PDF էջ ձեր սլայդի յուրաքանչյուր միջանկյալ վիճակի համար (օրինակ՝ հինգ էջ հինգ ցուցակի տարրերի համար, եթե դրանք ցուցադրվում են մեկը մյուսի հետևից): Սա թույլ կտա ձեզ օգտագործել նման PDF ֆայլը որպես առանձին ներկայացում՝ հաշվետվություն ներկայացնելիս:

Ավտոմատ հավաքում և հրապարակում ինտերնետում

Հարմար է, երբ սլայդները կոմպիլացվում են ավտոմատ կերպով, երբ փոփոխություններ են կատարվում տարբերակների կառավարման համակարգում, և նույնիսկ ավելի հարմար է, երբ ավտոմատ կերպով կոմպիլացված սլայդները տեղադրվում են ինտերնետում՝ ընդհանուր օգտագործման համար: Ինտերնետից սլայդները կարող են հեշտությամբ «նվագարկվել» լսարանի առջև՝ ինտերնետին միացված ցանկացած մեքենայից և պրոյեկտորից:

Քանի որ մենք մեր աշխատանքում օգտագործում ենք GitHub-ը, CI համակարգի բնական ընտրությունը հետևյալն է. TravisCI, և պատրաստի ներկայացումներ հյուրընկալելու համար - github.ioGithub.io-ի գաղափարն այն է, որ ցանկացած ստատիկ բովանդակություն մղվում է ճյուղ gh-pages Ձեր GitHub-ի նախագիծը հասանելի կդառնա հետևյալ հասցեով՝ <ваше имя>.gihub.io/<ваш проект>.

TravisCI-ի ամբողջական կոնֆիգուրացիայի ֆայլ, որը ներառում է էջի HTML տարբերակի Maven-ով կոմպիլյացիան, decktape-ով դրա PDF-ի փոխակերպումը և արդյունքների ճյուղավորումը։ gh-pages github.io-ում հրապարակման համար, կարծես այնքան.

TravisCI-ի կողմից նման նախագիծ կառուցելու համար անհրաժեշտ է կարգավորել միջավայրի փոփոխականները

GH_REF — github.com/inponomarev/csa-hb ձևի արժեքը
GH_TOKEN — GitHub մուտքի տոկեն։ Դուք կարող եք այն ստանալ GitHub-ում՝ ձեր պրոֆիլի կարգավորումներում, Մշակողի կարգավորումներ -> Անձնական մուտքի տոկեններ։ Եթե դուք ներկայացում եք հրապարակում հանրային պահոցում, ապա այս տոկենի համար անհրաժեշտ է նշել միայն «Մուտք հանրային պահոցներ» մուտքի միակ մակարդակը։
GH_USER_EMAIL / GH_USER_NAME — անուն/էլ. փոստի զույգ, որի անունից կկատարվի թեմայի հղումը gh-pages.

Այսպիսով, GitHub-ում ներկայացման կոդի յուրաքանչյուր «commit» ավտոմատ կերպով վերակառուցում է HTML և PDF սլայդները և վերբեռնում դրանք github.io: (Իհարկե, դուք պետք է github.io-ում վերբեռնեք միայն այն ներկայացումները, որոնք ցանկանում եք ի վերջո հրապարակային դարձնել):

Նախագծերի օրինակներ

Վերջապես, ահա հղումներ Travis-CI-ի համար կարգավորված Maven սկրիպտներով և CI կոնֆիգուրացիայով մի քանի օրինակելի շնորհանդեսային նախագծերի, որոնք կարող եք կլոնավորել և օգտագործել ձեր սեփական շնորհանդեսային նախագծերը ստեղծելիս.