Onion Information
Dokumentiranje programa alatom MkDocs - GASERI
MkDocs je brz i jednostavan alat za generiranje projektne dokumentacije. Izvorni kod dokumentacije piše se u formatu Markdown, a MkDocs generira izlazni HTML u skladu s postavkama navedenim u konfiguracijskoj datoteci u formatu YAML
Onion Details
Page Clicks: 1
First Seen: 03/15/2024
Last Indexed: 10/23/2024
Onion Content
Preskoči na sadržaj Dokumentiranje programa alatom MkDocs je brz i jednostavan alat za generiranje projektne dokumentacije. Izvorni kod dokumentacije piše se u formatu Markdown , a MkDocs generira izlazni HTML u skladu s postavkama navedenim u konfiguracijskoj datoteci u formatu YAML . Stvaranje početnih datoteka Naredbom mkdocs s argumentom new možemo stvoriti početnu konfiguraciju (datoteka mkdocs.yml ) i primjer dokumentacije (datoteka docs/index.md ): $ mkdocs new moja-dokumentacija $ cd moja-dokumentacija Prevođenje izvornog koda u HTML za pregled vršimo naredbom mkdocs s argumentom serve : $ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory INFO - Documentation built in 0 .22 seconds [ I 201101 19 :13:50 server:296 ] Serving on http://127.0.0.1:8000 [ I 201101 19 :13:50 handlers:62 ] Start watching changes Izlaz možemo pregledati otvaranjem web preglednika na adresi 127.0.0.1 i vratima 8000 . Uređivanje konfiguracije i sadržaja Markdown i YAML datoteke možemo uređivati korištenjem bilo kojeg uređivača teksta. Primjerice, možemo koristiti Visual Studio Code koji ima ugrađenu podršku za Markdown i Red Hatovo proširenje za YAML tako da u njemu otvorimo direktorij moja-dokumentacija . U datoteci mkdocs.yml promijenimo ime stranice promjenom postavke site_name : Moja dokumentacija Iskoristimo Lorem Markdownum za generiranje sadržaja i spremimo rezultat u datoteku docs/lorem.md . Definirajmo navigaciju da uključuje obje datoteke tako da u mkdocs.yml dodamo naredbu nav i navedemo obje datoteke s odgovarajućim naslovima: site_name : Moja dokumentacija nav : Početna : index.md - 'Lorem Markdownum' : lorem.md Pritom smo naslov 'Lorem Markdownum' stavili pod navodnike zbog razmaka u riječi. Nakon spremanja MkDocs će sam uočiti da su datoteke izmijenjene i ponovno izgraditi HTML datoteke. Kad smo zadovoljni rezultatom, izgradnju web sjedišta pokrenut ćemo naredbom: $ mkdocs build što će stvoriti direktorij site i u njemu HTML datoteke index.html i lorem/index.html , zbog čega ćemo moći imati lijepe URL-e / i /lorem/ (respektivno). Ova naredba ima nekoliko parametara čiji je opis moguće dobiti parametrom --help , a istaknut ćemo samo parametar --clean koji će isprazniti direktorij site prije izgradnje sjedišta, što je korisno za brisanje datoteka pod starim imenima nakon preimenovanja. Zadatak Proučite upute za generiranje hijerarhije u navigaciji u dijelu Writing your docs . Zatim generirajte dva nova dokumenta korištenjem Lorem Markdownuma i spremite ih u datoteke lorem-est.md i lorem-qui.md te sva tri dokumenta postavite u navigaciji pod 'Lorem Markdownum' s naslovima pojedinih dokumenata u skladu s naslovima koje je generator dao. Zadatak Proučite upute za konfiguraciju Configuration pa postavite ime autora, opis sjedišta i informacije o autorskom pravu, a zatim pogledajte izvorni kod stvorenog HTML-a te u njemu pronađite postavljene informacije. Uključite ekstenziju SmartyPants te u nekom od dokumenata isprobajte navodnike te dvostruke i trostruke crtice da se uvjerite da radi. Author: Vedran Miletić