Sphinx-doc

Overview

Op deze pagina: http://www.sphinx-doc.org/en/stable/install.html#windows-install-python-and-sphinx staan de stappen die je moet maken om sphinx te installeren op windows. Als alle stappen zijn voltooid Sphinx worden gebruikt vanuit de command-line. Heel globaal worden de volgende stappen gebruikt:

1. Python installeren
2. Sphinx (inclusief plugins & extensies) installeren
3. Sphinx-build aanroepen

Daarna komt nog een klein stukje over editors e.d. om de documentatie toe te voegen

Python installeren

Dit kan worden gedaan via een URL op de website. Je doorloopt hierbij een installer. Het is hier belangrijk dat je aanvinkt dat je Python wil toevoegen aan environment variables. Ook zal een optie zijn om pip te installeren. Dit moet je ook aanvinken. (Het installeren via Anaconda is ook een mogelijkheid)

Note

Gebruik altijd de laatste, stabiele python3 versie!

Sphinx (& extensies)

Sphinx is geschreven in python en wordt met de python-package manager pip geïnstalleerd. Let op dat je _pip3_ gebruikt, als je ook een python2 geïnstalleerd hebt.

pip install sphinx

pip install sphinxcontrib.napoleon
pip install sphinxcontrib-plantuml

Mocht het niet lukken om PlantUML te installeren dan moet je eerst pip updaten:

pip install --upgrade pip setuptools

Plantuml (de jar file)

De plantuml-extensie gebruikt het java programma PlantUML. Dat je kunt downloaden van: http://plantuml.com. PlantUML gebruik (onderwater) “graphviz” (ook wel: dot, dotty); zie: https://www.graphviz.org. En natuurlijk heb je java nodig - dat is gelukkig redelijk standaard. En je moet al die zaken correct aan elkaar knopen.

Al met al is dat best lastig. Maar er zijn wat tussenstappen mogelijk. Zorg dat je eerst PlantUML (zonder Sphinx) aan de slag krijgt. Dat staat goed beschreven op: http://plantuml.com/starting

De laatste, lastigste, stap is PlantUML automatisch laten aanroepen vanuit Sphinx; dat doet de eerder genoemde extensie, aam de hand van de conf.py file. Die laatste mag je niet aanpassen; als kan het handig zijn om dat lokaal tijdelijk te doen, als je er anders niet uitkomt.

Deze laatste stap hoort “out-of-the-box” te werken, mits je plantuml.jar op een van de standaard plekken geïnstalleerd hebt. Of je een (bash, hulp) scriptje plantuml gebruikt.

Warning

TOOLS ARE NOT PART OF THE SOURCE

Some advices “on the internet” will you to place the plantuml.jar file inside the project environment. And commit it to version-controll…

THAT IS WRONG! You are not support (nor allowed) to do so!

Documentatie builden

Documentatie builden betekent dat je de rst bestanden omzet naar een werkende website die je lokaal kan bekijken. Om te builden, ga in de command-line naar ...\pathways-extensions-training\docs Eenmaal hier type het volgende commando in:

sphinx-build -c doc -b html doc __result\html

Na de build is er een build directory (__result/html) toegevoegd. Ga hier in en open index.html. Hiermee kan je de documentatie op de website bekijken. Iedere keer als je nieuwe wijzigingen wil bekijken of testen moet je dit build commando gebruiken.

Note

Die gegenereerde file (__result/...) moeten natuurlijk niet gecommit worden.

In de standaard configuratie gebeur dat niet. Doordat die directory opgenomen in de .hgignore file

Documentatie aanpassen

Notepad++

Notepad++ is de editor die gebruikt wordt voor het bewerken van rst en andere typen bestanden van de documentatie. Deze kan gevonden worden op: https://notepad-plus-plus.org/download

Using RST

Sphinx heeft een eigen documentatie over het gebruik van RST. Deze kan hier worden gevonden: http://www.sphinx-doc.org/en/stable/rest.html Naast deze documentatie zijn er ook andere voorbeelden te vinden op het internet.

Theme veranderen

Warning

Not needed

You may ignore the remainder of this article

There is no need to change the theme. The theme only specifying the layout and colors of generated documentation. By having other colors for a local build and the official (RTfD) ones, it easy to see to which version you are looking!

Whenever, you give it a try; be sure you NEVER commit conf.py!

Het thema zorgt ervoor dat je build er precies hetzelfde uitziet als de live website. Hiervoor moet je twee stappen volgen:

1. Installeer het correcte thema:

pip install sphinx_rtd_theme

2. Voeg het volgende toe in conf.py:

html_theme = "sphinx_rtd_theme"

Belangrijk: Zorg ervoor dat je deze wijziging in conf.py niet meecommit. Gebruik dit alleen om de build lokaal te testen.

Als deze stappen gevolgd zijn kan je het nogmaals builden. Als je de site dan bekijkt, zul je zien dat het thema hetzelfde is als de live website.