Demo: Project documentation bouwen

datum:12/06/2017

Deze pagina bevat de instructie om de documentatie voor dit project op te bouwen. Het is in de vorm van een demonstratie zodat je kan laten zien hoe je de documentatie opbouwt. Aan het einde van de (korte) demonstratie kunt u een RekenRobot-teampage maken en aanpassen, met behulp van Sphinx.

Hulpmiddelen

Een beschrijving van de plugins, en de installatie daarvan, die je nodig hebt voor het maken van de documentatie vind je onder Version Control, Sphinx-doc en Setup on laptop van de training pagina.

In het kort heb je voor deze demo de volgende installaties nodig:

• Python 3.6 (64-bits)
• Sphinx
• Mercurial 4.2.1 (64-bits)
• Een clone van de repository

Op de bovenstaande instructiepagina vind ook een globale uitleg hoe je de documentatie moet opbouwen. Deze instructie geeft specifiek aan hoe je de teampagina aanmaakt en wijzigingen doet.

Opzet demo

Na het opzetten van de demo kan je praktisch alles wat je tijdens de demo wilt laten zien. Pas na vaker gebruik krijg je ook handigheid in het opmaken via rst.

Stap 1 - bestaande documentatie op te bouwen met Sphinx

Zorg dat je een clone van de repository lokaal op je PC hebt staan. Alle files voor de documentatie staat in de map .pathways-extensions-trainingdocs. Voer het onderstaande commando uit in cmd om de pagina te bouwen:

sphinx-build -c doc -b html  -d tmp/sphinx_cache  doc/ __result/html

Dit zorgt ervoor dat er een mapje __results in de map doc komt met daarin het bestand index.html. Als je hier dubbel op klikt zou de Read the Docs pagina lokaal moeten openen.

Stap 2 - eigen teampagina aan te maken en bouwen

Ga naar de map pathways-extensions-trainingdocsdocteams en maak een nieuwe map aan, conform het template jaaral.volgnummer_teamnaam. Kopieer het index.rst bestand van een vorig team naar de map. Pas de inhoud van dit bestand aan voor jullie team en sla het bestand op. Bouw de pagina op met het Sphinx commando wat in de readme staat. Door het Sphinx commando te draaien wordt de map __results in de docs map gecreerd. In deze map staan alle html bestanden die zijn opgebouwd uit de rst code. Vind het bestand wat je gemaakt hebt en je zult zien dat jullie teampagina erbij staat. Eigenlijk heb je nu al het eerste gedeelte van de demo laten zien.

Demo

Elke Teampagina heeft een MopGallerij! Maak een nieuw bestand aan in de teammap en noem die MopGallerij.rst. Pas ook de index.rst aan door ‘MopGallerij’ onder te toctree te zetten run het build commando. De demo is geslaagd als de pagina lokaal geopend kan worden. De pagina kan je openen door een ()