Sa huling dalawang taon ay mas naging kasangkot ako sa dokumentasyon. Ang pagsulat ng isang tekstong nagpapaliwanag tungkol sa kung paano gumagana ang isang partikular na sistema ay karaniwang medyo simple. Ang pagguhit ng isang diagram na magpapakita ng lahat ng mga pangunahing bagay at ang mga koneksyon sa pagitan ng mga bagay na ito ay medyo madali din.
Ngunit ang pinakaproblemadong aspeto ay ang pagpapanatiling napapanahon ang dokumentasyong ito. At magiging maayos ang teksto, ngunit ang mga diagram... Dahil... lahat ng dokumentasyon ay online, ibig sabihin. sa html na format, pagkatapos ang teksto ay sinamahan ng gif/jpeg/png mga larawan, na aktwal na nagpapakita ng mga diagram. At ang mga diagram ay iginuhit sa iba't ibang mga programa tulad ng Visio o mga serbisyong online a la draw.io. Pagkatapos ay i-export mo ang diagram sa graphic na format at ilakip ito sa html. Simple lang.
Ano ang problema?
Ang mga scheme ay karaniwang simple. Mas tiyak, hindi masyadong kumplikado. Oo, ang bilang ng mga bagay ay isang dosena o dalawa, ang bilang ng mga koneksyon ay halos pareho. Dagdag na mga lagda, ilang mga pagtatalaga. Ang mga simpleng scheme ay maaaring ilarawan sa mga salita, ngunit masyadong kumplikado, ahem... (c) "hindi nila maintindihan, ginoo." Mayroong maraming mga scheme, ang mga pagbabago ay kailangang gawin sa kanila nang pana-panahon, episodic, i.e. patuloy, dahil sinusunod nila ang pagbuo ng ating mga produkto.
Maaari mong i-embed ang html ng serbisyo. Nasubukan mo na ba?
Oo ba. Halimbawa, gusto ko ang mga graphics mula sa gliffy.com. Ngunit para gumawa ng mga pagbabago, kailangan mong pumunta sa isang third-party na serbisyo at mag-edit doon. At mas mahirap italaga ang mga pagwawasto sa isang kasamahan.
Ano ang dapat gawin?
Kamakailan lamang ay nakatagpo ako ng isang repositoryo sa Github sa mga rekomendasyon . Diagram bilang code. Yung. inilalarawan namin ang circuit na kailangan namin sa js. Isinulat namin ang js na ito nang direkta sa parehong html kung saan naroon ang iba pang teksto ng dokumentasyon.
Sa pamamagitan ng paraan, nagsusulat ako ng dokumentasyon na hindi ganap sa html. Karaniwan, ang dokumentasyon ay isang hanay ng mga file na may markdown text, na pagkatapos ay iko-convert sa isang ganap na site ng dokumentasyon ng ilang makina, halimbawa wintersmith. O isang sistema ng wiki.
Ito ay napaka-maginhawa: isinulat namin ang teksto, pagkatapos ay bubukas ang script tag at ang JS code ng scheme ay inilarawan dito.
Ano na naman ang mali?
Nagustuhan ko ang repositoryong ito, ngunit hindi lamang ito ang halimbawa kung saan ang isang diagram ay iginuhit gamit ang code o isang representasyon ng teksto. (Sa dulo ng artikulo ay magkakaroon ng mga link sa mga proyekto at artikulo na na-Google ko sa diagram ng paksa bilang code.)
At hindi lang ako ang nag-e-edit ng dokumentasyon. Minsan ang mga kasamahan ay nag-aambag din - iwasto ang isang salita, baguhin ang isang paglalarawan, magpasok ng mga bagong larawan.
Samakatuwid, gusto kong makita ang diagram sa isang nababasa, nauunawaan na format ng teksto na hindi mangangailangan ng mahabang curve sa pag-aaral. At sa ilang mga lugar ay maaari mo ring i-copy-paste upang mapabilis ang pagdaragdag ng isang bagong circuit.
At sinabi ng isa pang kasamahan na ang code ay, siyempre, mabuti, ngunit kung gagamit ka ng istraktura, ang lahat ay maaaring maging napakahigpit at nagpapahayag.
Samakatuwid, sinubukan kong isipin ang diagram bilang isang set ng ilang maliliit na array na naglalarawan ng mga node, koneksyon, grupo ng mga node, pati na rin ang lokasyon ng mga node. Ito ay, sa aking mapagpakumbabang opinyon, medyo maginhawa, bagaman, siyempre, ang lasa at kulay...
Paano ito isang tsart sa isang array?
- Ang bawat node ay inilalarawan ng isang identifier na natatanging nagpapakilala sa node.
- Maaari ka ring magdagdag ng icon sa node at magdagdag ng inskripsiyon.
- Maaari mong tukuyin ang isang relasyon sa pagitan ng dalawang node.
- Para sa komunikasyon sa diagram, maaari mong itakda ang kulay at inskripsyon.
- Ang direksyon ng komunikasyon ay tinukoy bilang mula sa pinagmulan hanggang sa target. At ang pinagmulan at target ay ipinahiwatig ng mga node identifier.
- Ang isa o higit pang mga node ay maaaring idagdag sa isang pangkat.
- Ang relasyon ay maaari ding tukuyin mula sa grupo at sa grupo.
Gamit ang mga simpleng panuntunang ito, nakukuha natin ang sumusunod na diagram. Basta? medyo.
At ito ay inilarawan ng sumusunod na js code. Ang pangunahing bagay dito ay ang object object. Kung saan ang mga node ay ipinahiwatig - mga node, mga gilid - mga koneksyon.
const elements = {
nodes: [ // ΠΎΠΏΠΈΡΡΠ²Π°Π΅ΠΌ ΡΠ·Π»Ρ
{ id: 'client', type: 'smartphone', label: 'Mobile App'},
{ id: 'server', type: 'server', label: 'Main Server'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [ // ΡΠΊΠ°Π·ΡΠ²Π°Π΅ΠΌ ΡΠ²ΡΠ·ΠΈ
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
Siyempre, hindi ako mismo ang nag-drawing ng circuit, ngunit ginamit ko ang library ay isang napakalakas na tool sa visualization. Gumagamit lamang ako ng isang maliit na bahagi ng mga posibilidad sa aking solusyon.
Okay, ito ay isang simpleng halimbawa. Maaari ba itong maging mas kumplikado?
Oo pakiusap. Upang ipahiwatig ang mga posisyon, gumagamit kami ng mga posisyon, upang ipahiwatig ang mga pangkat, ipinapahiwatig namin ang isang listahan ng mga pangkat sa mga pangkat, at ang mga elemento mismo ay may katangian ng pangkat.
At ito ang code:
<div id="scheme5" style="height:500px;width:800px;"></div>
<script>
const elements5 = {
groups: [
{ id: 'g1', label: 'ΠΡΡΠΏΠΏΠ° ΡΠ΅ΡΠ²ΠΈΡΠΎΠ² 1'},
{ id: 'g2', label: 'ΠΡΡΠΏΠΏΠ° ΡΠ΅ΡΠ²ΠΈΡΠΎΠ² 2'},
],
nodes: [
{ id: 'man1', type: 'person', label: 'Π§Π΅Π»ΠΎΠ²Π΅ΠΊ'},
{ id: 'client', type: 'smartphone', label: 'Π‘ΠΌΠ°ΡΡΡΠΎΠ½'},
{ id: 'agent-backend', type: 'server', group: 'g1', label: 'agent-backend'},
{ id: 'web', type: 'server', group: 'g1', label: 'ΠΡΠΈΠ»ΠΎΠΆΠ΅Π½ΠΈΠ΅ admin'},
{ id: 'www', type: 'server', group: 'g1', label: 'ΡΡΡΠ°Π½ΠΈΡΠ° Π·Π°Π³ΡΡΠ·ΠΊΠΈ'},
{ id: 'mongodb1', type: 'database', group: 'g1', label: 'Mongo DB 1'},
{ id: 'mongodb2', type: 'database', group: 'g1', label: 'Mongo DB 2'},
{ id: 'runner-integration1', type: 'worker', group: 'g1', label: 'ΠΎΡΠΏΡΠ°Π²ΠΊΠ°'},
{ id: 'runner-integration2', type: 'worker', group: 'g1', label: 'ΠΎΡΠΏΡΠ°Π²ΠΊΠ°'},
{ id: 'api', type: 'server', group: 'g1', label: 'API'},
{ id: 'server2', type: 'server', group:'g2', label: 'ΡΠ΅ΡΠ²Π΅Ρ'},
{ id: 'otherServer', type: 'server', group:'g2', label: 'ΡΠ΅ΡΠ²Π΅Ρ'},
{ id: 'firebase', type: 'cloud', label: 'Google Firebase'},
],
edges: [
{ source: 'client', target: 'agent-backend', label: 'json', color: 'red' },
{ source: 'agent-backend', target: 'mongodb1', color: 'red' },
{ source: 'agent-backend', target: 'mongodb2', color: 'red' },
{ source: 'mongodb1', target: 'runner-integration1', label: 'Π΄Π°Π½Π½ΡΠ΅' },
{ source: 'mongodb2', target: 'runner-integration2', label: 'Π΄Π°Π½Π½ΡΠ΅' },
{ source: 'mongodb1', target: 'web', label: 'Π΄Π°Π½Π½ΡΠ΅ Π΄Π»Ρ ΠΎΡΠΎΠ±ΡΠ°ΠΆΠ΅Π½ΠΈΡ' },
{ source: 'runner-integration1', target: 'server2', label: 'Π΄Π°Π½Π½ΡΠ΅' },
{ source: 'runner-integration2', target: 'otherServer', label: 'Π΄Π°Π½Π½ΡΠ΅' },
{ source: 'api', target: 'firebase', label: 'Π·Π°ΠΏΡΠΎΡΡ', color: 'blue', },
{ source: 'firebase', target: 'client', label: 'push', color: 'blue'},
{ source: 'server2', target: 'api', label: 'ΡΠ²Π΅Π΄ΠΎΠΌΠ»Π΅Π½ΠΈΡ', color: 'blue'},
{ source: 'man1', target: 'client', },
],
positions: [
{ id: 'client', row: 2, col: 1,},
{ id: 'agent-backend', row: 2, col: 3,},
{ id: 'web', row: 6, col: 3,},
{ id: 'www', row: 1, col: 3,},
{ id: 'mongodb1', row: 1, col: 4,},
{ id: 'mongodb2', row: 2, col: 5,},
{ id: 'runner-integration1', row: 3, col: 3,},
{ id: 'runner-integration2', row: 4, col: 3,},
{ id: 'api', row: 5, col: 3,},
{ id: 'server2', row: 6, col: 7,},
{ id: 'otherServer', row: 4, col: 7,},
{ id: 'firebase', row: 5, col: 1,},
{ id: 'logger', row: 2, col: 7,},
{ id: 'crm', row: 5, col: 8,},
],
};
Diagram('scheme5', elements5, {layout: 'grid'});
</script>
Sa isang banda, ang gayong pamamaraan ay halos isang pares ng mga screen ng code sa isang laptop, sa kabilang banda, ang istraktura a la json ay nagpapahintulot sa iyo na punan ang lahat ng data sa pamamagitan ng pagkakatulad, nang mabilis at maaari mong kopyahin-i-paste.
Bakit inilalagay ang mga posisyon nang hiwalay sa mga node?
Ito ay mas komportable. Una, tinukoy namin ang mga node. Pagkatapos ay maaari naming tukuyin ang isang pares ng mga grupo at ipahiwatig ang mga ito sa mga node. Pagkatapos ay itinalaga namin ang mga koneksyon. At pagkatapos lamang, kapag ang mga pangunahing bagay at koneksyon sa pagitan ng mga ito ay naroroon, kinukuha namin ang lokasyon ng mga bagay na ito sa diagram. O vice versa.
Posible bang walang posisyon?
Posible ito nang walang mga posisyon. Ngunit ito ay medyo gusot; makikita mo ang pagpipiliang ito sa mga halimbawa. Ito ay dahil sa ang katunayan na mayroong isang algorithm para sa lokasyon ng mga node para sa cytoscape , na isinasaalang-alang din ang pagkakaroon ng mga grupo. Ang pagtukoy ng mga posisyon ay ginagawang mas nakokontrol ang diagram, ngunit sa yugto ng unang draft ng diagram posible nang walang mga posisyon.
Ang mga posisyon ay maaari ding tukuyin sa istilo ng Battleship. Yung. ang isang node ay matatagpuan sa a1, at ang isa pa sa d5. Ito ay lalo na nakakatulong na ang cytoscape ay ginagawang magagalaw ang mga bagay sa canvas, i.e. maaari naming ilipat ang mga ito sa paligid, tingnan ang iba't ibang mga pagpipilian sa layout, at pagkatapos ay ayusin ang pag-aayos ng mga elemento na gusto namin sa code.
Sa pangkalahatan, ito ay nauunawaan. Maaari mo ring subukan?
Siyempre, upang mabilis na lumikha ng mga circuit, ginawa ko ang aking sarili na maliit , na mismong nag-a-update ng schema at nag-iimbak ng pinakabagong bersyon sa browser (sa localStorage).
Nasubukan mo na ba? Maaari mo na itong idagdag sa iyong pahina.
Pero:
1. Pagkonekta ng script
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Magdagdag ng code sa html
<div id="scheme1" style="height:300px;width:800px;"></div>
<script>
const elements = {
nodes: [
{ id: 'client', type: 'smartphone', label: 'Mobile App'},
{ id: 'server', type: 'server', label: 'Main Server'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
</script>
3. ini-edit namin ang code sa diagram na kailangan namin (sa tingin ko ito ay mas madali kaysa sa pagguhit ng isang kuwago :)
Higit pang mga detalye sa sa github.
Ang resulta?
Nakamit ko ang aking mga layunin - upang magdagdag ng mga inline na diagram sa dokumentasyon, ang format ay medyo simple at naiintindihan. Hindi ito angkop para sa mga super circuit, ngunit para sa maliliit na circuit na nagpapaliwanag sa istruktura ng mga koneksyon, ito ay ganap na maayos. Maaari mong palaging mabilis na mag-tweak at magbago ng isang bagay sa paglipas ng panahon. Oo, at ang mga kasamahan ay maaaring magtama ng isang bagay sa dock mismo, kahit na mga caption para sa mga bagay, nang walang espesyal na pagsasanay))
Ano ang maaaring mapabuti?
Mayroong, siyempre, maraming mga pagpipilian dito. Magdagdag ng mga karagdagang icon (lahat ng mga umiiral na ay idinaragdag inline sa script). Pumili ng mas nagpapahayag na hanay ng mga icon. Gawing posible na tukuyin ang estilo ng linya ng koneksyon. Magdagdag ng larawan sa background.
Ano sa tingin mo?
Mayroon na akong ilang mga ideya para sa pagpapatupad sa mga isyu, maaari mo ring idagdag ang sa iyo sa mga komento.
Ang aking solusyon ay tiyak na naaangkop sa isang makitid na hanay ng mga problema, at marahil ay makakahanap ka ng isang mas maginhawang tool para sa pagguhit ng mga diagram sa pamamagitan lamang ng pag-coding sa mga ito - gaya ng sinasabi nilang 'ipakita sa akin ang iyong diagram bilang code'
- (9 na uri ng mga chart online na editor)
- At kung gusto mo ng sobrang detalyado at kumplikadong mga diagram, tiyak na hahangaan mo ang proyektong ito:
Pinagmulan: www.habr.com