Zadnjih par godina sam se sve više bavio dokumentacijom. Pisanje teksta s objašnjenjem o tome kako funkcionira ovaj ili onaj sustav općenito je prilično jednostavno. Crtanje dijagrama koji će prikazati sve ključne objekte i veze između tih objekata također je prilično jednostavno.
Ali najproblematičniji aspekt je ažuriranje te dokumentacije. I tekst bi bio u redu, ali dijagrami... Jer... sva dokumentacija je online, tj. u html formatu, tada uz tekst idu gif/jpeg/png slike, koje zapravo prikazuju dijagrame. A dijagrami se crtaju u raznim programima kao što je Visio ili online servisi a la draw.io. Zatim izvozite dijagram u grafički format i priložite ga html-u. Jednostavno je.
U čemu je problem?
Sheme su obično jednostavne. Točnije, ne baš komplicirano. Da, broj objekata je desetak ili dva, broj priključaka je približno isti. Plus potpisi, neke oznake. Jednostavne sheme se mogu opisati riječima, ali presložene, hm... (c) "neće razumjeti, gospodine." Postoji mnogo shema, potrebno ih je mijenjati povremeno, epizodno, tj. stalno, jer prate razvoj naših proizvoda.
Možete ugraditi html usluge. Jeste li probali?
Da naravno. Na primjer, sviđa mi se grafika s gliffy.com. Ali da biste unijeli promjene, morate otići na uslugu treće strane i tamo urediti. A još je teže delegirati ispravke kolegi.
Što učiniti?
Nedavno sam u preporukama naišao na repozitorij na Githubu . Dijagram kao kod. Oni. opisujemo krug koji nam treba u js. Ovaj js pišemo izravno u istom html-u u kojem se nalazi drugi tekst dokumentacije.
Usput, pišem dokumentaciju ne u potpunosti u html-u. Tipično, dokumentacija je skup datoteka s markdown tekstom, koji se zatim pretvara u potpunu dokumentacijsku stranicu pomoću nekog stroja, na primjer Wintersmitha. Ili wiki sustav.
Ispada vrlo zgodno: napisali smo tekst, zatim se otvara oznaka skripte i u njoj je opisan JS kod sheme.
Što opet nije u redu?
Svidjelo mi se ovo spremište, ali ovo nije jedini primjer gdje je dijagram nacrtan pomoću koda ili prikaza teksta. (Na kraju članka bit će poveznice na projekte i članke koje sam guglao na dijagramu teme kao kod.)
I nisam jedini koji uređuje dokumentaciju. Nekad i kolege daju svoj doprinos - isprave koju riječ, izmijene opis, ubace nove slike.
Stoga bih želio vidjeti dijagram u čitljivom, razumljivom tekstualnom formatu koji ne zahtijeva dugo učenje. A na nekim mjestima čak možete jednostavno kopirati i zalijepiti kako biste ubrzali dodavanje novog kruga.
I drugi kolega primijetio je da je kodeks, naravno, dobar, ali ako koristite strukturu, sve može biti vrlo strogo i izražajno.
Stoga sam dijagram pokušao zamisliti kao skup nekoliko malih nizova koji opisuju čvorove, veze, grupe čvorova, kao i položaj čvorova. Ispalo je, po mom skromnom mišljenju, prilično zgodno, iako, naravno, okus i boja...
Kako je ovo grafikon u nizu?
- Svaki čvor je opisan identifikatorom koji jedinstveno identificira čvor.
- Također možete dodati ikonu u čvor i dodati natpis.
- Možete odrediti odnos između dva čvora.
- Za komunikaciju na dijagramu možete postaviti boju i natpis.
- Smjer komunikacije definiran je kao od izvora do cilja. A izvor i cilj označeni su identifikatorima čvorova.
- Grupi se može dodati jedan ili više čvorova.
- Odnos se također može odrediti i od grupe i prema grupi.
Koristeći ova jednostavna pravila, dobivamo sljedeći dijagram. Samo? Dosta.
I to je opisano sljedećim js kodom. Glavna stvar ovdje je objekt elemenata. U kojem su čvorovi naznačeni - čvorovi, rubovi - veze.
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);
Naravno, nisam sam smislio crtež strujnog kruga, već sam koristio biblioteku je vrlo moćan alat za vizualizaciju. Koristim samo djelić mogućnosti u svom rješenju.
U redu, ovo je jednostavan primjer. Može li biti kompliciranije?
Da molim. Za označavanje pozicija koristimo pozicije, za označavanje grupa označavamo popis grupa u grupama, a sami elementi imaju atribut grupe.
A ovo je kod:
<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>
S jedne strane, takva shema je gotovo nekoliko ekrana koda na prijenosnom računalu, s druge strane, struktura a la json omogućuje vam da popunite sve podatke po analogiji, brzo i možete kopirati-zalijepiti.
Zašto su pozicije postavljene odvojeno od čvorova?
Udobnije je. Prvo specificiramo čvorove. Tada možemo odrediti nekoliko grupa i označiti ih u čvorovima. Zatim označavamo veze. I tek tada, kada su glavni objekti i veze između njih, preuzimamo položaj tih objekata na dijagramu. Ili obrnuto.
Može li se bez pozicija?
Može i bez pozicija. Ali bit će malo zgužvan, ovu opciju možete vidjeti u primjerima. To je zbog činjenice da postoji algoritam za lokaciju čvorova za cytoscape , koji također uzima u obzir prisutnost grupa. Određivanje položaja čini dijagram lakšim za kontrolu, ali u fazi prvog nacrta dijagrama to je moguće i bez položaja.
Pozicije se također mogu odrediti u stilu bojnog broda. Oni. jedan čvor se nalazi u a1, a drugi u d5. Posebno pomaže to što cytoscape čini objekte na platnu pokretljivima, tj. možemo ih pomicati, vidjeti različite opcije izgleda i zatim popraviti raspored elemenata koji nam se sviđaju u kodu.
Općenito, to je razumljivo. Možete i vi pokušati?
Naravno, za brzo stvaranje sklopova, napravio sam si mali , koji sam ažurira shemu i pohranjuje najnoviju verziju u preglednik (u localStorage).
Jeste li probali? Sada ga možete dodati na svoju stranicu.
S druge strane:
1. Povezivanje skripte
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Dodajte kod u 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. uređujemo kod u dijagram koji nam je potreban (mislim da je lakše nego crtati sovu :)
Više detalja na na githubu.
Rezultat?
Postigao sam svoje ciljeve - dodati inline dijagrame u dokumentaciju, format je prilično jednostavan i razumljiv. Nije prikladan za super sklopove, ali za male sklopove koji objašnjavaju strukturu veza, sasvim je u redu. Uvijek možete brzo nešto dotjerati i promijeniti s vremenom. Da, i kolege mogu sami ispraviti nešto u pristaništu, barem natpise za objekte, bez posebne obuke))
Što se može poboljšati?
Ovdje, naravno, postoji mnogo opcija. Dodajte dodatne ikone (sve postojeće dodaju se u skripti). Odaberite izražajniji skup ikona. Omogućite određivanje stila spojne linije. Dodajte pozadinsku sliku.
Što misliš?
Već imam nekoliko ideja za implementaciju u izdanjima, također možete dodati svoje u komentarima.
Moje rješenje je definitivno primjenjivo u uskom rasponu problema, a možda ćete pronaći prikladniji alat za crtanje dijagrama jednostavnim kodiranjem - kako kažu 'pokažite mi svoj dijagram kao kod'
- (9 vrsta online uređivača grafikona)
- A ako volite super detaljne i složene dijagrame, onda ćete se sigurno diviti ovom projektu:
Izvor: www.habr.com