-
Notifications
You must be signed in to change notification settings - Fork 6
Modulien konfigurointi
Kuten kuvattu sivulla Sivuston rakenne, Rakennetun ympäristön tietomallit-sivuston sisältö koostuu valtaosin erillisistä tietomoduleista, jotka on liitetty yhteen sivuston konfiguraatiossa. Kullakin modulilla on oma konfiguraatiotiedostonsa ja osoitepolkunsa perusosa (basepath), jota vastaa docs-hakemiston alihakemisto. Modulin sisältösivut on sijoitettu tämän alihakemiston all joko osana ry-tietomallit -GitHub-repoa tai sitten osana ko. tietomodulin omaa git-submodule -linkitettyä GitHub-repoa. Ensin mainittu tapa toimii kehitys- ja ohje-moduleissa, joista ei ole tarpeen olla saatavilla kuin uusin versio, ja joiden sisällön muuttuminen ei aiheuta ongelmia. Tähän kategosriaan kuuluvat tavallisesti esimerkiksi kehitysprojektien ja niiden lopputuotosten kuvaukset. Jälkimmäinen tapa toimii paremmin tapauksissa, joissa modulin sisällön pysyvät ja muuttumattomat julkaisuversiot on tarkoitus tuottaa käyttäen git-versionhallintaa, koska tällöin kukin ko. git-repon tiettyä julkaisuversiota vastaava tagi voidaan linkittää omaksi versiokohtaiseksi alihakemistokseen ry-tietomallit-repon alle. Tietomallien ja niiden soveltamisprofiilien kuvaukset ja niihin liittyvät säännöstöt on syytä toteuttaa tällaisinä versionhallittuina moduleina, sillä on todennäköistä, että samasta tietomallista tulee voida tukea useampaa julkaisuversiota yhtä aikaa, ja eri tietojärjestelmät ja niiden käyttämät fyysiset tietomallit perustuvat mahdollisesti tietomallien vanhempiin julkaisuversioihin.
Konfiguraatiotiedoston avulla muodostetaan modulin sisäinen navigaatiorakenne, tuotetaan modulikohtainen versiovalitsin, tarvittavat linkit osoittamaan modulin sisältöihin sen GitHub-repossa, ja noudetaan kunkin sisältösivun metatiedot, kuten viimeisin muutosaika ja -historia. Konfiguraatiotiedostot on kuvattu YAML-kielellä, ja sivusto Jekyll-sivumoottori lukee niiden tiedot muistiin, jossa niitä hyödynnetään sivujen generointiin sivuston Liquid-kielisissä makroissa.
Kunkin tietomodulin konfiguraatiotiedostot ovat osa ry-tietomallit -GitHub-repoa, ja ne sijaitsevat hakemistossa docs/_data/modules/. Modulin tiedostonimi ilman .yml-päätettä muodostaa sen yksilöivän tunnuksen. Sekä versioitavien että ei-versioitavien modulien konfiguraatiotiedostot sijaitsevat samassa hakemistossa.
Seuraavan esimerkin avulla esitetään kaikki modulikonfiguraatiotiedoston tiedot, jotka ry-tietomallit -sivustolla on käytössä.
title: "Kaavatiedot" # modulin otsikko, jota käytetään, kun moduli linkitetään päätason valikkoon
ownership: "ympäristöministeriö" # modulin omistajatieto, ei vielä esitetä sivustolla
note: "Fyysiset mallit (Kaava-JSON ja Postgre) on siirretty Asema- ja yleiskaavojen tietomallit -kehitysprojektin alle" # huomautus, joka näytetään modulin navigaatiopalkissa
github: # versiodun modulin GitHub-repon tiedot
owner_name: "sykefi"
repository_name: "kaavatietomalli"
versions: # ry-tietomallit -sivustolla julkaistujen versioiden tiedot
- id: "v1.0" # versiotunnus
title: "Asema- ja yleiskaavan tietomallit -projektin lopputulos" # version otsikko
path: "v1.0" # version alihakemiston polku
default: true # oletusversion asetus
- id: "dev"
title: "Seuraava kehitysversio"
path: "dev"
git-branch: "develop" # git-repon haara, annettava jos ei oletushaara
development: true # kyseessä on kehitysversio, joka voi vielä muuttua
dependencies: # ko. version riippuvuudet muista moduleista ja niiden versioista. Käytetään muodostettaessa modulien kuvaussivujen välisiä, versiokohtaisia linkkejä
- moduleId: "yhteisetkomponentit"
version: "dev"
basepath: "kaavatiedot" # toimii sekä modulin osoitepolun perusosana (https://tietomallit.ymparisto.fi/kaavatiedot/...) että sen alihakemiston nimenä (docs/kaavatiedot/...)
nav_items: # Modulin sisäinen navigointivalikko. Samat sivut ovat olemassa kaikissa julkaisuversioissa
- pageId: "johdanto" # sivun tunnus, yksilöivä modulin sisällä
title: "Johdanto" # sivun otsikko
path: "" # sivun osoitepolku. Jos ei ole annettu, oletetaan, että polku on "<basepath>/[<versioId>/][<groupId>/]<pageId>/"
gitHubFile: "index.md" # sivun Markdown-muotoinen sisältötiedosto GitHubissa. Jos ei ole annettu, oletetaan löytyvän joko linkitetyn GitHub-sisältörepon polusta "[<groupId>/]<pageId>/index.md" tai ei-versioitujen modulien tapauksessa ry-tietomallit-repon polusta "docs/<basepath>/[<groupId>/]<pageId>/index.md"
default: true # modulin oletussivun asetus
- pageId: "kasitemalli"
title: "Käsitemalli"
- groupId: "looginenmalli" # navigointiryhmän tunnus
title: "Looginen tietomalli"
nav_items: # navigaatioryhmän alisivut
- pageId: "dokumentaatio"
title: "Dokumentaatio"
- pageId: "uml-doc"
title: "UML-kaaviot"
path: "uml/doc/" # polku annettu tässä, koska se ei ole sivutunnuksen mukainen "looginenmalli/uml-doc/"
gitHubFile: "uml/kaavatietomalli.xml" # tässä kiinnitetty sivun muutostiedot XMI-tiedostoon, koska markdown-sisältö ei yleensä muutu
- pageId: "elinkaarisaannot"
title: "Elinkaarisäännöt"
gitHubFile: "elinkaarisaannot.md" # GitHub-tiedosto annettu tässä, koska poikkeaa oletuksesta "looginenmalli/elinkaarisaannot/index.md"
path: "elinkaarisaannot.html"
- pageId: "laatusaannot"
title: "Laatusäännöt"
gitHubFile: "laatusaannot.md"
path: "laatusaannot.html"
- pageId: "inspire"
title: "Inspire-yhteensopivuus"
gitHubFile: "inspire.md"
path: "inspire.html"
- pageId: "muutosloki"
title: "Muutosloki"
path: "muutosloki.html"
gitHubFile: "muutosloki.md"Modulin sisäinen navigaatio tukee vain yhtä sisäkkäistä navigaatioryhmää, eli ryhmän alla olevat mahdolliset aliryhmät eivät tule navigaatiossa näkyviin.
- Tällä hetkellä versioitujen modulien yhteydessä ei voi olla sivuja, jotka eivät ole versioriippuvaisia, ja toisaalta kaikissa julkaisuversioissa on oltava täsmälleen samat sivut. Tästä voisi pyrkiä eroon, ks. seikka #37.
- Kullakin modulilla olisi hyvä olla metatietosivu, jossa modulikonfiguraation tiedot (mm. omistaja ja GitHub-repo) esitetään HTML-muodossa, ks. seikka #45.