Onderhoud

Zoals met de meeste langdurige projecten heeft ook deze documentatie onderhoud nodig. Dit onderhoud wordt gedaan door curatoren die artikelen toevoegen, aanpassen en, wanneer nodig, verwijderen. The volgende secties beschrijven hoe genoemde onderhoud wordt gedaan en de afgesproken conventies.

Curator Informatie

Deze documentatie wordt gehost door Read the Docs, een industrie standaard manier om documentatie voor software of in-house gidsen/tutorials. Een aantal voorbeelden van bedrijven die RTD gebruiken:

RTD documentatie pagina’s worden in het ReStructuredText formaat geschreven. ReST is een markup taal, wat betekent dat sommige characters zoals een asterisk (#) of een underscore (_) een andere betekenis hebben dan alleen tekst. Je hebt wellicht vergelijkbare formaten zoals HTML of Markdown in gebruik gezien op websites of GitHub. Het kost wat moeite en tijd om te schrijven in ReST, maar met de help van dit cheatsheet heb je de basis al snel te pakken. Het is aanbevolen om een IDE te gebruiken die de syntax van ReST support zodat het programma aangeeft wanneer je in correct ReST schrijft. Deze Visual Studio Code extensie regelt dat voor je.

Deze documentatie wordt gehost via RTD, maar de daadwerkelijke source bestanden zijn te vinden in onze GitHub repository. De website bouwt automatisch een nieuwe versie wanneer een commit is gepushed naar een branch van de repository. Het is erg aanbevolen om een basis begrip van Git the hebben, via je IDE en/of commandline, om netjes de documentatie te onderhouden.

Tip

Als je een basis les nodig hebt over het gebruik van Git en Github is dit een goede plek om te beginnen.

Om aan deze documentatie te werken moet je een werkende versie van poetry hebben. Poetry is een Python dependency manager die alle benodigde software installeert om te werken aan deze documentatie. Je kan poetry installeren via het pip commando. Als je pip niet geïnstalleerd hebt zal je eerst moeten checken of je wel een werkende versie van Python hebt.

Installeer poetry via pip:

pip install poetry

Onderhoud Process

Het process voor het veranderen of toevoegen aan de huidige documentatie gaat als volgt:

  • De curator forked van de main repository of creërt een nieuwe branch voor de gewenste aanpassingen [1].
  • De curator veranderd of voegt artikelen, pagina’s en secties toe volgens de Conventies.
  • De curator genereert vertaling files en/of vertaalt handmatig de artikelen.
  • De curator commit all veranderingen.
  • De curator creërt een pull request met een andere curator als reviewer zodat de edits dubbel gechecked kunnen worden voordat ze in de algehele documentatie verschijnen.

Onderhoud Gids

Notitie

Hou er rekening mee dat deze gids bedoeld is voor simpele verandering of de toevoeging van een enkele pagina. Als er grote veranderingen worden toegepast is het aanbevolen om eerst andere files te bekijken om te zien hoe hun ReStructuredText is opgebouwd.

Fork eerst de repository of creër een nieuwe branch [1] van de main repository. Clone daarna de repository lokaal naar je computer:

git clone <repository link>

<repository link> moet vervangen worden met de bijbehorende link van de repository. Als een nieuwe branch was gecreërd voor de aanpassingen die je zou willen toevoegen, moet je naar die branch switchen:

git checkout -b <branch name>

<branch name> moet vervangen worden met de name van de nieuwe branch.

Om te zorgen dat alle dependencies zijn geïnstalleerd, voer het volgende commando uit:

poetry install

Vervolgens kan je de aanpassingen in de pagina’s toevoegen of kopiëer je de template.rst naar een sectie binnen \docs om een nieuwe pagina te maken. Zorg dat je de Conventies goed volgt. Vervolgens moeten de localizatie (vertaling) files geupdate worden. Bouw eerst een nieuwe set .rst files vanuit de huidige map [2]:

poetry run sphinx-build -b gettext . _build/gettext

Vervolgens update je de Engels en Nederlandse localizatie bestanden:

poetry run sphinx-intl update -p _build/gettext -l en
poetry run sphinx-intl update -p _build/gettext -l nl

In order to keep the documentation nicely synced between English and Dutch it’s recommended that you go into the locale\nl\LC_MESSAGES folder and translate the page you have edited. Next, stage and commit all changes:

git add -A
# Stage all changes
git commit
# Commit all changes to the directory

Vervolgens moet je de gecommitte veranderingen uploaden naar de remote repository:

git push --origin

Als je geen GUI tool gebruikt om je Git mappen te beheren zal je hier waarschijnlijk voor een password prompt. De commandline is een onwijs handige en machtige tool, maar in dit geval is het soms makkelijker om via VS Code of Git GUI je Git veranderingen te beheren.

Tot slot creër je een pull request en wijs je een reviewer toe. Wanneer de reviewer al je veranderingen accepteert zal de website automatisch een nieuwe versie bouwen van de documentatie.

Notitie

Omdat het over het algemeen professioneel is om niet op de huidige stabiele release van een project veranderingen te maken is het ook mogelijk om het eindresultaat alvast te zien in een werk versie. Deze versie is niets meer dan een branch op Github, maar deze branch moet wel geactiveerd op readthedocs.org.

Conventies

Het template.rst bestand zal ervoor zorgen dat je de conventies automatisch al deels volgt, maar hier is een kleine lijst om rekening mee te houden tijdens het schrijven in artikelen van de documentatie:

  • Begin een pagina altijd met een hoofdtitel.
  • Een pagina moet altijd eindigen met een .. sectionauthor: Je Naam directive om te onderscheiden wie het artikel heeft geschreven op de website.
  • Gebruik admonitions en andere formatterings tools zo vaak en precies mogelijk. Het is beter om té duidelijk te zijn dan een vage documentatie hebben.

Voetnoten

[1](1, 2) De creatie van een nieuwe branch is alleen mogelijk als de curator is toegevoegd als collaborator in Github of als eigenaar van het project.
[2]Het is belangrijk om een basis begrip te hebben van de command line en hoe om te gaan met mappen en bestanden.

Auteur van deze sectie: Bo Kamphues