MkDocs telepítése
Egy projekt életciklusában fontos, hogy mind az aktív, mind az újonnan csatlakozó csapattagok számára egy központi helyen legyenek gyűjthetőek és elérhetőek a projekttel kapcsolatos legfontosabb információk.
Pl.:
- Fejlesztői környezet beüzemelésének leírása
- Projekt konvenciók leírása
- Gyakran felmerülő problémák és megoldási módszereik
- stb.
Ehhez az MkDocs statikus weboldal generátort használjuk, mellyel egy jól struktúrált, könnyen szerkeszthető és átlátható dokumentáció készíthető.
Az MkDocs általi weboldal generálás YML fájllal konfigurálható, az egyes oldalak pedig Markdown nyelven írt md kiterjesztésű fájlok.
A generáláshoz szükséges fájlokat egy külön Git repository-ban tároljuk. A generálás során előállt statikus weboldalból pedig docker image készíthető és a projekt tagjai számára elérhető helyre publikálható.
Telepítés
Python és Python package manager telepítése
Az MkDocs telepítés előfeltétele, hogy a számítógépünkre telepítve legyen a Python és a hozzátartozó Python package manager (pip). A Python az alábbi oldalról tölthető le és telepíthető:
A letöltés után indítsuk el a telepítést, de figyeljünk oda, hogy a Custom telepítést válasszuk. Ha a rendszerre bízzuk a telepítést, akkor a lenti képeken látható opciókat nem fogjuk elérni. A problémát az jelenti, hogy például a környezeti változók sem kerülnek beállításra a sima telepítés során.
A Python telepítése során figyeljünk rá, hogy az Optional Features képernyőn a „pip“ opció legyen bepipálva így nem kell majd utólag telepítenünk:
Ezt követően az Advanced Options képernyőn pipáljuk be az „Add Python to environment variables“ opciót, hogy a python automatikusan bekerüljön a környezeti változók közé:
A Python és a pip már előre telepítve van macOS rendszeren, így azt nem szükséges ebben a lépésben telepíteni.
Python virtuális környezet létrehozása
Erre azért van szükség, hogy az MkDocs-hoz szükséges függőségeket ne a rendszerszintű python-ba telepítsük. A lentebb látható parancsok kiadása előtt érdemes létre hozni egy mappát, egy tetszőleges helyen, amibe dolgozol. A kiadott parancsok következtében az adott mappában jönnek létre a szükséges fájlok.
Virtual environment manager telepítése:
Virtuális környezet létrehozása:
Virtuális környezet aktiválása:
Virtuális környezet deaktiválása
Szükség esetén az alábbi paranccsal tudjuk deaktiválni a python virtuális környezetet:
MkDocs telepítése
-
Klónozzuk le magunkhoz a
documentationrepository-t. -
A projekt főkönyvtárában adjuk ki az alábbi parancsot:
Használat
Előnézet megnyitása
Amennyiben dokumentációt lokális környezeten szeretnénk böngészőben megtekinteni, akkor azt az alábbi paranccsal tehetjük meg:
Ezt követően a localhost:8000 linken megtekinthető a dokumentáció előnézete.
Amennyiben lokálisan futtatjuk a python service-t, akkor port ütközésbe futhatunk. Ilyen esetben futtassuk egy másik porton az mkdocs service-t
Ezt követően a localhost:8001 linken megtekinthető a dokumentáció előnézete.
Új oldal létrehozása
Az oldal tartalmának megírása
Egy új oldal létrehozásához egy markdown nyelven írt md fájlt kell létrehozni. A létrehozott fájlt documentation repository docs mappáján belül a megfelelő package alá mentsük el.
A különféle stíluselemekhez az Angular Material eszközkészletét használjuk. Az Angular Material MkDocs-ban is használható dizájn komponenseit itt lehet megtekinteni: Material for MkDocs
Az oldal bekötése a dokumentációba
Ahhoz, hogy az md fájlunk megjelenjen a generált dokumentációban, definiálnunk kell hogy milyen útvonalon legyen elérhető a weboldalon.
Ezt az mkdocs.yml fájl nav: szekciójában tudjuk megtenni.
- A legfelső blokk írja le, hogy melyik menüpont alatt lesz megtalálható az új dokumentáció.
- Az alsóbb blokkokkal definiálható, hogy melyik almenüben legyen megtalálható az új dokumentáció.
A megfelelő blokkban megadva az md fájlunk útvonalát elérhetővé válik az új oldal.