Respec documentatie generatie

• Kennis van git/GitHub
• Kennis van Markdown en/of HTML
• Een webserver om de documentatie te hosten

Voor de laatste gebruiken wij GitHub. Kennis van de vorm van een Javascript object is handig om de in dit template voorkomende scripts aan te kunnen passen maar zonder die kennis kom je m.b.v. deze documentatie ook al heel ver.

Om het gebruik van dit template makkelijker te maken raden we het aan om een IDE te gebruiken. Die geeft een voorbeeld van hoe de markdown eruit zal zien, kan laten zien of de config files nog in de correcte vorm zijn en kan helpen in het gebruik van git.
Een gratis voorbeeld van een IDE is: Visual studio code. Een combinatie van GitHub desktop en je eigen favoriete Markdown editor is echter ook mogelijk.

Aanpassingen maken aan het document gaat op 2 manieren:

• De configuratie van het document aanpassing in de config files
• Markdown of html files toevoegen/veranderen

De configuratie files bevatten informatie over de organisatie en over de status van het document. Helemaal onderaan hoofdstuk 3 vind je meer informatie over de configuratie opties, daarnaast kun je ook de Logius ReSpec wiki bezoeken. De files zijn gesplitst in 2 files die weer in 2 verschillende repositories zijn ondergebracht: organisation-config.js en config.js.

De organisation_config (organisation-config.js) bevat configuratie properties die betrekking hebben op alle VNG-R Respec documentatie, de properties in deze file zullen zelden veranderen zoals bijv. de naam van de organisatie.

De document_config (config.js) bevat configuratie properties die alleen relevant is voor het betreffende Respec document en hoort dan ook in elke Respec renderende repository thuis.

Beide configuratie bestanden worden gelinkt in de index.html file waardoor ze beide bij het renderen van de Respec documentatie automatisch worden samengevoegd. Daardoor zijn de organisatie specifieke configuraties over alle Respec documentatie van VNG-R gelijk en hoeft deze niet steeds gekopieerd te worden. Op deze wijze zorgen we er voor dat alle VNG-R Respec documenten zo eenduidig mogelijk zijn en blijven.

In het volgende hoofdstuk staat beschreven hoe je de inhoud van het Respec document naar wens kunt aanpassen.

Het bestand '.github/workflows/build.yml' bevat een action script waarmee automatisch een drietal acties worden uitgevoerd nadat een bestand in de repository wordt gewijzigd, toegevoegd of verwijderd:

• het renderen van het Respec document;
• het checken of de gerenderde Respec html wel correct is en voldoet aan de toegankelijkheidseisen;
• het publiceren van de gegenereerde statische html en pdf naar een centrale Respec publicatie repository.

We beschrijven de eerste 2 acties in het kort hieronder. Aangezien we de laatste actie nog niet werkende hebben wordt deze voorlopig nog handmatig uitgevoerd, dat beschrijven we in hoofdstuk 4. De log van deze acties is te vinden in het tabblad Actions in de GitHub repository.

alternateFormats: [
  {
      label: "pdf",
      uri: "snapshot.pdf",
  },
]

Het is mogelijk om met Imvertor Respec documentatie te genereren van een model. Voorwaarde is wel dat het model MIM compliant is. Bij het genereren spelen de volgende Imvertor configuratieproperties (LET OP! Dus niet een van de Respec property bestanden) een rol:

Voor het genereren van Respec documentatie is het essentieel om in je lokale Imvertor property bestand de property 'createofficevariant' de waarde 'respec' te geven. Normaliter zal je dan ook de property 'createofficemode' de waarde 'click' geven. Dit resulteert er in dat in de folder 'app/cat' 2 Respec bestanden geplaatst, 1 in html en de ander in xhtml.

Standaard zet Imvertor alle in Enterprise Architect gedefinieerde diagrammen om naar PNG images. Deze images worden echter niet als img elementen opgenomen in de gegenereerde (x)html. Indien dat gewenst is dan zul je ze zelf moeten opnemen. Het is echter wel mogelijk om deze diagrammen automatisch als clickable images in de gegenereerde (x)html op te nemen. Om dat te kunnen doen moet wel aan een aantal voorwaarden worden voldaan.

1. Alleen diagrammen die direct geplaatst zijn in de root folder (Stereotype = 'Basismodel') of in de folder waarin (de folder met) de componenten staan worden daarbij meegenomen. Ze mogen dus ook niet in een subfolder van deze folders worden geplaatst;
2. De diagrammen moeten class diagrams zijn;
3. De naam van de diagrammen moet als suffix '- overzicht' of '- detail' hebben;

Tenslotte is de onderstaande Imvertor configuratieproperty nog van belang.

Als deze de waarde 'yes' heeft of niet geconfigureerd is worden er in de (x)html bestanden img elementen met referenties naar de juiste images en imagemap elementen opgenomen.

LET OP! Maak de in Respec op te nemen diagrammen zoveel als mogelijk in portrait mode op. Dat voorkomt dat je nodeloos diep op het Respec document moet inzoomen.

1. Open het VNG-R Respec template en klik in de README op die pagina op de link 'Use this template';
2. Je komt nu in het menu om een nieuwe repository aan te maken waarbij al een aantal velden zijn ingevuld. De te maken repository mag niet private zijn want dat maakt het gebruik van GitHub Pages onmogelijk. Geef de van de aanvrager verkregen repository naam in en klik op 'Create repository';
3. Voer de acties, zoals beschreven in de handleiding voor het initieel inrichten van GitHub repositories, uit;
4. Verwijder in de root van de repository het 'README.md' bestand en hernoem 'Alt-README.md' naar 'README.md'

Dat bestand moet nog gecreëerd worden in het template;

6. Activeer GitHub Pages voor de nieuwe repository. Selecteer daarvoor het tabblad 'Settings' en kies daar 'Pages';
7. Kies daar waar bij Branch 'None' staat voor 'main' en klik op 'Save';
8. Nadat de build en deployment is uitgevoerd ga je naar het 'Code' tabblad, klikt daar op het tandwieltje bij 'About' en klikt op de checkbox naast 'Use your GitHub Pages website'. Klikken op de resulterende link onder 'About' brengt je naar de standaard gegenereerde Respec documentatie die nu kan worden aangepast door de eigenaar van de repository;

Je beschikt nu over een repository die je kunt gaan vullen en waarin je je persoonlijke configuratie properties van een waarde kunt voorzien. Indien je een met Imvertor gegenereerd Respec html bestand wil gebruiken dan volg je de beschrijving van de volgende paragraaf, zo niet dan ga je direct naar de daarop volgende paragraaf.

Zoals aangegeven maken we in het Respec framework gebruik van een aantal VNG-R properties. Properties die er voor zorgen dat alle Respec documentatie van VNG-R eenzelfde look en feel heeft. Er zijn echter ook een aantal lokale configuratie properties waarmee voor ieder Respec document eigen keuzes kunnen worden gemaakt. Denk daarbij aan de status die het document heeft, de publicatie datum, de editors, etc...

Alle lokale configuratie properties kun je vinden in 'js/config.js' en mag je naar eigen inzicht aanpassen.

Er moet nog bepaald worden welke properties lokaal moeten zijn en welke globaal (dus welke behoren te staan in de repository 'Respec-Organization-configurations').

Hieronder vind je de totale lijst van Configuratie properties. De vierde kolom geeft aan of het om een globale of lokale property gaat. Voor enkele properties is dat heel logisch, zo zijn 'localizationStrings' en 'previousPublishVersion' logischerwijs globaal, 'github' en 'title' zijn juist weer lokaal. De meeste globaal gedefinieerd properties kunnen lokaal overruled worden zoals 'useLogo'. Doe dat echter alleen als daar een hele goede reden voor is.

LET OP!
De hieronder uitgewerkte structuur van de publicatie GitHub repository is slechts een voorstel.

Voor het publiceren van alle Respec documenten in de GitHub repository 'publicatie' is de hieronder beschreven consistente structuur vereist. Deze consistente structuur moet overeenkomen met de waarde van in het globale configuratiebestand gedefinieerde properties 'latestVersion', 'thisVersion' en 'prevVersion'. Indien wordt besloten de inhoud van die properties aan te passen dan heeft dat ook gevolgen voor de repository structuur.

In dit overzicht vertegenwoordigd x.x.x het versienummer van het Respec document. De folder met die naam kan zich herhalen maar komt minimaal 1x voor, de huiidge versie. De inhoud van die folder wordt dan eveneens geplaatst in de folder [project-mnemonic]. project-mnemonic is Hieronder zie je een voorbeeld van deze structuur:

Tijdens het samenstellen van de inhoud van een nieuwe versie of een geheel nieuw Respec document kun je de structuur in de 'publicatie' repository al aanpassen. Betreft het de eerste versie van een Respec document creëer dan direct in de folder 'cim' een nieuwe folder die als naam de mnemonic van het project krijgt. Daarbinnen creëer je een versiefolder met als naam het versienummer waaronder je de eerste versie publiceert. Bestaat de projectfolder al wel dan creëer je in die folder een nieuwe versiefolder met als naam het versienummer waaronder je de nieuwe versie publiceert. In beide folders creëer je voorlopig een leeg 'index.html' bestand.

Na generatie kan het bestand 'snapshot.html' en het pdf bestand vanuit de GitHub repository waarin ze gegenereerd zijn worden gekopieerd naar de projectfolder en naar de naar de zojuist aangemaakte versiefolder in de 'publicatie' repository. Het bestand 'index.html' verwijder je vervolgens in beide folders waarna je 'snapshot.html', eveneens in beide folder, hernoemt naar 'index.html'.

Pas vervolgens in de root van de publicatie repository de 'index.md' aan zodat je toegang hebt tot alle Respec documentatie en de http links kunt kopiëren voor gebruik in andere GitHub Pages documentatie.

Definitie: Een definitie is een beschrijving van een woord. Een ander woord voor definitie is betekenis of beschrijving. De notatiewijze voor het definiëeren van een definitie is als volgt:

<dfn>Definitie</dfn>

Deze definities worden opgenomen in de bijlage 'Index'.

Afbeeldingen krijgen een nummer en vermelding in de figurenlijst 10. Lijst met figuren.

Referentie uit globale [SemVer] of lokale [MIM] localBiblio lijst. Deze lijst staat in de organisation-config.js of config.js, zie hieronder een voorbeeld.

  localBiblio: {
        "MIM": {
           "href": "https://docs.geostandaarden.nl/mim/mim/",
           "publisher": "Geonovum",
           "title": "MIM - Metamodel Informatie Modellering",
            date: "Oktober 2013",
            rawDate: "2023"
        },
    },

Alleen referenties die ook echt in de tekst voorkomen worden in de bijlage 'Referenties' getoond. De notatie voor het opnemen van een referentie is [ [xxxx] ].

We gebruiken de notatie <a>xxxxx<</a> om een referentie naar een in het document aangebrachte definitie te creëren. Het resultaat ziet er dan bijv. zo definitie uit.

De onderstaande secties (Conformiteit e.d.) zijn optioneel, zie index.html:

<body>
  <section id="abstract" data-include-format="markdown" data-include="abstract.md"></section>
  <section id="sotd"></section><!-- Wordt automatisch gevuld -->
  <section data-include-format="markdown" class="informative" data-include="ch01.md"></section>
  <section data-include-format="markdown" data-include="ch02.md"></section>
  <!-- Hieronder optionele secties. Worden automatisch gevuld -->
  <section id='conformance'></section>
  <section id='tof'></section>
  <section id="index"></section>
</body>