Workflow studieboeken

eboek
quarto
Publicatiedatum

14 april 2021

Gewijzigd

9 februari 2023

Samenvatting

Uitleg over de workflow voor de productie van mijn studieboeken.

Overzicht

De cursusboeken worden gemaakt en gepubliceerd met Quarto, een open-source wetenschappelijk en technisch publicatiesysteem gebouwd op Pandoc. Een Quarto document bevat platte tekst in Markdown formaat, eventueel R-code voor het genereren van grafieken en diagrammen en metadata in YAML formaat.

Het bijhouden van alle fases van de cursusboeken wordt met versiebeheer gedaan. Het gebruikte versiebeheersysteem is Git, open source en gratis. Dit is lokaal op mijn computers geïnstalleerd. Elk cursusboek is georganiseerd in een project (= een map/directory) op mijn lokale PC, dat in versiebeheer ook wel een repository genoemd wordt. Daarnaast staan de repositories van de cursusboeken ook op GitHub, een online platform (cloud), voor iedereen toegankelijk.

Uit de brondocumenten wordt een publicatie gemaakt, meestal in een van de volgende eindformaten: HTML (voor online gebruik), PDF of EPUB. De HTML onlineversie is in feite een statische website, een map met inhoud, zonder gebruik van een database en kan op elke webserver geplaatst worden.

De hosting van de cursusboeken is ondergebracht bij Netlify, een bedrijf voor o.a webhosting, maar eentje die integratie met GitHub aanbiedt. Voor persoonlijk gebruik is Netlify gratis met een totaal gebruik van 100GB/maand. Upgraden kan, maar daar hangt een prijskaartje aan. Het gebruik wordt gemonitord met Google Analytics.

Samenvatting workflow

  1. Er wordt lokaal eenmalig een projectmap aangemaakt en hierin Git versiebeheer geactiveerd waardoor het een Git repository wordt.
  2. Er wordt op GitHub een remote repository gemaakt van de lokale repository.
  3. Met RStudio Desktop worden de Quarto documenten gemaakt en bijgewerkt.
  4. Na wijzigingen wordt de repository bijgewerkt en gesynchroniseerd met de repository op GitHub.
  5. Het publiceren op Netlify verloopt via een Quarto opdracht.

Gebruikte software

Markdown

Markdown is een erg eenvoudige opmaaktaal, zie Wikipedia. Het aantal tags is beperkt. De bestandsextensie is .md. Wanneer je een lokaal bestand met een browser opent zie je alleen de platte tekst. Applicaties kunnen een .md bestand omzetten naar HTML. Wanneer je op GitHub een .md bestand met de browser open dan wordt deze automatisch omgezet naar HTML.

Het werken ermee is laagdrempelig. Het schrijven kan met een kladblokprogramma, je ziet dan weliswaar de opmaak in HTML formaat niet. Dat kan wel met een van de vele gratis Markdown editors of met Microsoft’s Visual Studio Code. Zelf gebruik ik RStudio Desktop. Ook zijn er addons voor browsers.

R

R is een (gratis) programmeertaal voor statistische berekeningen en grafieken en beschikbaar voor Windows, MacOS en Unix/Linux. Bij de installatie zit een eenvoudige GUI en een console. Via de console kun je R opdrachten intypen en direct laten uitvoeren. Via de Gui kun je een bestand met R opdrachten maken (R-script), opslaan en uitvoeren.

Je kunt met de standaard meegeleverde Gui werken, maar veel plezieriger en handiger is het om met RStudio Desktop te werken. Dat is een zeer goede IDE van de firma RStudio die als gratis open source editie beschikbaar is. Wanneer je met R werkt kun je eigenlijk niet zonder.

Quarto

Quarto wordt meegeleverd bij de installatie van RStudio Desktop, maar dit is meestal niet de laatste versie. Je kunt dan ook beter Quarto afzonderlijk downloaden en installeren.

Een Quarto bestand (extensie .qmd) is een Markdown bestand waarin je ook code (R, Python, …) kunt opnemen. Hieruit kan dan een document geproduceerd worden dat naast de opgemaakte markdown tekst ook de uitvoer van de code bevat, zoals bijvoorbeeld een grafiek.

Je hoeft niet perse code op te nemen. Het kan ook zonder en alleen Markdown tekst bevatten. Je blijft dan het voordeel houden dat je van de fantastische uitvoermogelijkheden gebruik kunt maken. Voor de cursusboeken is geen R-code nodig. Toch gebruik ik soms R-code om dynamisch grafieken, tabellen en diagrammen te maken.

Git

Git is een versiebeheersysteem, beschikbaar voor Windows, macOS en Unix/Linux, waarmee je veranderingen van bestanden in een werkmap (repository) bijhoudt. Je kunt hierdoor steeds zien welke veranderingen er in welke bestanden zijn geweest en door wie die zijn aangebracht. Je kunt ook de werkmap terugzetten naar een eerdere toestand in de tijd, een eerdere versie van de werkmap. Je moet de Git software installeren op elke computer van waaraf je wilt werken. Na installatie zijn er twee Git clients beschikbaar:

  • Git Bash - een terminal, vergelijkbaar met de Windows command terminal
  • Git Gui - een eenvoudige Gui

Vanuit deze clients kun je Git-opdrachten uitvoeren. Je moet dan wel de syntax van de opdrachten kennen en letterlijk intypen. Veel programmeurs werken op deze manier.

Er zijn ook (gratis) Git GUI clients met meer mogelijkheden, zoals GitKraken (Windows, Mac & Linux) en SourceTree (Windows, Mac). En ook in de RStudio Desktop is een Git client geïntegreerd.

Erg handig is dat je in Git zeer eenvoudig een nieuwe branche (aftakking) kunt maken. Deze aftakking staat los van de hoofdtak (master of main geheten) en je kunt hierin eigen ontwikkelingen doen. Het is mogelijk om zo’n aftakking weer samen te voegen met de hoofdtak.

GitHub

GitHub is een online platform dat in eerste instantie bedoeld was voor het plaatsen van bronbestanden voor open source software. Het is gebouwd rond Git en is gaandeweg een zeer groot en geavanceerd ontwikkelplatform geworden. GitHub is in 2018 door Microsoft overgenomen.

Voor het maken van een repository op GitHub moet je eerst een (gratis) account maken. Je kunt er prive repositories plaatsen, maar de meeste repositories zijn public en zijn voor iedereen toegankelijk, in die zin dat je de inhoud kunt bekijken en naar je eigen computer kunt klonen. Voor mijn repositories op GitHub zie: https://github.com/bwelman.

Netlify

Netlify is een hosting platform met een op Git gebaseerde workflow en uitvoerige mogelijkheden tot integratie met repositories op GitHub. Het proces ziet er schematisch als volgt uit:

flowchart LR
  ben[Lokale werkmap] --> |aanpassingen| github[GitHub repository]
  github --> |publiceren| netlify[Website op Netlify]
Figuur 1: Publiceren met Netlify

Samenwerking

Er zijn meerdere mogelijkheden tot samenwerking. Een GitHub repository heeft hiervoor een aantal tabs:

  • Issues - Vooral bedoeld om fouten te melden en verzoeken om nieuwe onderdelen/mogelijkheden toe te voegen.
  • Discussions - Voor het voeren van een discussie over iets, voor het stellen en beantwoorden van vragen, voor het delen van informatie, voor het doen van aankondigingen.
  • Pull requests - Dit is het verzoek van iemand om zijn branch in de hoofdtak op te nemen. In die branch zitten voorgestelde wijzigingen. De eigenaar van de repository bekijkt deze wijzigingen en neemt dan een beslissing tot wel of niet opnemen.

Issues en discussions zijn eenvoudig te gebruiken en daar kan ook eigenlijk niets mis gaan. Een pull request is wat ingewikkelder en heeft wat meer uitleg nodig.