GitBook je platforma, ktorá vám umožňuje vytvárať dokumentačné stránky alebo firemné wiki. Môžete ho použiť na dokumentáciu všetkých druhov vecí, od kódu po API a ako používať softvérový produkt.

GitBook používa podobný proces ako úložiská GitHub. Hlavná kópia dokumentácie funguje ako „hlavná“ kópia. Potom môžete vytvárať „koncepty“, ktoré sú podobné „pobočkám“.

Tento proces umožňuje mnohým používateľom pracovať na jedinej dokumentačnej lokalite a zároveň riešiť konflikty alebo im predchádzať. Umožňuje tiež, aby zmeny z rôznych vetiev prešli procesom kontroly pred ich zlúčením.

Ako začať používať GitBook

Môžete si vybrať z viacerých Ceny GitBook plány. Cena bude závisieť od toho, či GitBook používate na open source projekty, osobné použitie alebo súkromnú tímovú spoluprácu. GitBook je zadarmo na použitie, ak ho používate pre open source projekty.

GitBook podporuje Markdown, populárny značkovací jazyk s mnohými výhodami na písanie alebo dokumentovanie na webe.

GitBook sa tiež integruje s GitHub, platforma na hosťovanie, ukladanie a úpravu kódu

instagram viewer
. Svoj účet GitBook môžete prepojiť priamo so svojím účtom GitHub tak, že sa prihlásite pomocou svojich poverení GitHub.

  1. Zaregistrujte sa na GitBook. Ak máte svoj vlastný účet GitHub, môžete kliknúť na Zaregistrujte sa na GitHub.
  2. Po prihlásení vás GitBook presmeruje na novú internú wiki. Taktiež vopred vyplní vašu wiki nejakým ukážkovým obsahom.

Prehľad rozhrania GitBook

GitBook má niekoľko funkcií, ktoré vám umožňujú vytvárať a meniť vašu dokumentačnú stránku.

  1. Horný panel vám umožňuje vytvárať nové koncepty, zobrazovať históriu zmien alebo prezerať akékoľvek iné diskusie či prílohy.
  2. Bočný panel úplne vľavo vám umožňuje vytvoriť viacero medzier. Pre rôzne projekty môžete použiť samostatné priestory, aby ste mohli oddeliť a usporiadať oblasti dokumentácie. Bočný panel môžete rozbaliť alebo zatvoriť.
  3. Ľavý panel funguje ako ponuka pre stránku dokumentácie. Môžete si prezerať stránky v rámci vašej dokumentačnej lokality a použiť ju na vytváranie skupín a vnorených stránok. Na stránke sa môžete pohybovať aj pomocou uvedených odkazov.
  4. Spodný panel obsahuje tlačidlá, ktoré sú nevyhnutné pre proces kontroly verzií. Môžete pridať názov pre svoj koncept, zlúčiť zmenu alebo odoslať zmenu na kontrolu.

Ako vytvoriť nový koncept

Môžete vytvoriť nový koncept vytvorením novej požiadavky na zmenu a vykonaním zmien v nej.

  1. V hornom paneli kliknite na Žiadosti o zmenu.
  2. Na novom paneli, ktorý sa zobrazí na pravej strane, kliknite na Návrh tab. Toto vám ukáže všetky vaše aktívne koncepty.
  3. Odtiaľto môžete kliknúť na existujúci koncept a otvoriť ho. Ak chcete vytvoriť nový koncept, kliknite na Nová žiadosť o zmenua počkajte, kým sa stránka nedokončí.
  4. V dolnom paneli kliknite na Zadajte predmet. Tým sa otvorí okno, v ktorom môžete nový koncept pomenovať. Napríklad, Nová stránka - Ako nastaviť Codebase.

Ako vytvoriť stránky a skupiny

Keď máte koncept, môžete začať robiť zmeny v dokumentácii. GitBook ukladá vaše zmeny do konceptu, takže neovplyvnia hlavnú kópiu. Na pridávanie stránok a skupín stránok môžete použiť ľavý bočný panel.

  1. Vytvorte novú stránku kliknutím na Nová stránka odkaz v spodnej časti bočného panela a výber Nová stránka dokumentu z rozbaľovacej ponuky. Prípadne môžete umiestniť kurzor myši pod existujúcu stránku a kliknúť na modrú farbu plus tlačidlo.
  2. Ak chcete vytvoriť novú skupinu stránok, kliknite na Nová stránkaa vyberte položku Nová skupina možnosť z rozbaľovacej ponuky.
  3. Stránku môžete premenovať kliknutím na tri bodky vedľa stránky alebo skupiny a výberom Premenovať.
  4. Začnite pridávať obsah, aby sa naplnila vaša nová stránka. Môžete pridať jednoduchý obsah, ako je text alebo nadpisy. GitBook vám tiež umožňuje pridávať ďalšie bloky obsahu, ako sú obrázky, prílohy súborov, tabuľky, karty alebo úryvky kódu. K dispozícii je tiež možnosť pridať ďalšie integrácie, ako napríklad vloženie YouTube alebo obsah Dokumentov Google.
  5. Klikni na Rozdielny pohľad tlačidlo na spodnom paneli, aby ste videli rozdiely medzi vašou konceptom a originálnou kópiou hlavnej dokumentácie.
  6. Po dokončení písania obsahu môžete kliknúť na Zlúčiť, Odoslať a zlúčiť, alebo Odoslať na kontrolu.

K odkazu na zdieľanie sa dostanete z horného panela GitBook. Ak chcete zobraziť prepojenie, musíte byť mimo konceptu a prezerať si kópiu hlavnej dokumentácie.

  1. V predvolenom nastavení je viditeľnosť vašej dokumentačnej lokality „neuvedená“. To znamená, že na stránku s dokumentáciou môžete pristupovať pomocou súkromného odkazu a nie cez vyhľadávače. Na hornom paneli kliknite na Neuvedené tlačidlo.
  2. V rozbaľovacej ponuke vyberte požadované nastavenia viditeľnosti. Upozorňujeme, že GitBook môže uzamknúť určité nastavenia viditeľnosti a možno budete musieť inovovať, aby ste k nim mali prístup.
  3. Pod zoznamom nastavení viditeľnosti sa nachádza odkaz, ktorý môžete zdieľať s ostatnými používateľmi, ktorí budú používať vašu stránku s dokumentáciou. Skopírujte tento odkaz a zdieľajte ho s ostatnými.
  4. Pod odkazom kliknite na Nastavenia odkazu a domény. Tu môžete prepojiť vlastný názov domény alebo upraviť časť adresy URL. Ak používate vlastnú doménu, môžete zobraziť Dokumentácia Gitbook ako správne nakonfigurovať DNS.

Vytváranie dokumentácie pomocou GitBook

GitBook vám umožňuje spoločne vytvárať a pracovať na dokumentačných stránkach alebo firemných wiki. GitBook si požičiava koncepty z GitHubu, ako sú vetvy a zlúčenie na kontrolu hlavnej kópie a riadenie akýchkoľvek konfliktov.

Môžete vytvoriť nový koncept a pridať svoje vlastné individuálne zmeny do dokumentácie. V rámci konceptu môžete vykonávať zmeny v obsahu, ako aj pridávať nové stránky alebo skupiny stránok. Po dokončení zmien ich môžete zlúčiť alebo odoslať na kontrolu.

Ak vytvárate internú dokumentáciu pre váš kód Java, možno budete chcieť preskúmať Javadoc. Javadoc vám umožňuje automaticky zdokumentovať váš kód Java.