Über diese FAQ

Diese FAQ dient zur Dokumentation der Infrastruktur und des Equipments der NerdBridge. Sie wird mit Sphinx erstellt und auf unserem Gitlab Server verwaltet und gehostet.

Ich will hier was schreiben

Awesome! Am besten Du kommst zum nächsten Clubtreffen und wir richten Dir zusammen alles ein, was Du benötigst. Falls Du schon Mal ein bisschen gucken willst, fange mal einen Account für unseren Gitlab Server an und beschäftigte dich mit git.

Danach kannst Du dir Sphinx auf deinem PC installieren.

Als Editor bietet sich Visual Studio Code an, da dieser für alles was benötigt wird entsprechende Erweiterungen bietet.

Funktionsweise

Sphinx arbeitet mit reStructuredText Dateien, welche das Ziel haben, in reiner Textform besonders gut lesbar zu sein. Die Dateien enthalten den eigentlichen Text der FAQ Seite, aber auch den so genannten toctree, welcher die Strukturierung des Seitenbaums festlegt.

Steueranweisungen beginnen immer mit .. am Anfang der Zeile. Neben dem toctree finden sich im Code der Seite Referezierungen (.. _refname:) auf die einzelnen Abschnitte der Seite, welche dann an anderen Stellen zum verlinken benutzt werden können.

Tipp

Die Syntax ist auf dem ersten Blick nicht besonders logisch. Am besten schaust Du dir die index.rst und eine normale Inhaltsseite als Orientierungshilfe an.

Minimalbeispiel

.. _refname-der-ganzen-seite:

Seitentitel
###########

.. toctree
   :maxdepth: 1

Beginn des normalen Seiteninhalts

Die toctree Anweisung gibt an, wie viele Ebenen des Seitenbaums im Seitenmenü angezeigt werden sollen. Das sind in unserer FAQ standardmäßig zwei.

Lokale Vorschau

Gerade wenn man das erste Mal mit reStructuredText zu tun hat, möchte man nicht bei jedem Versuch etwas bestimmtes zu erzeugen einen commit machen. Sphinx ist ein Generator welcher statisches HTML erzeugt und kann ganz einfach auf dem lokalen Rechner installiert und ausgeführt werden.

Wie so oft bei solchen Projekten ist es unter Linux und Mac einfach, unter Windows weniger. Für Linux und Mac gibt es entsprechende Pakete, welche mit yum, apt und brew installiert werden können. Unter Windows muss erst einmal Python 3 installiert werden, anschließend ist die Installation von Sphinx mit pip möglich.

Weitere Infos gibt es hier:

http://www.sphinx-doc.org/en/master/usage/installation.html

Ist Sphinx einmal installiert und der Code mit git ausgecheckt, erzeugt folgender Befehl eine neue lokal gerenderte Version der FAQ:

sphinx-build -a -b html -d _build/doctrees . _build/html

Tipp

Falls Du dir nicht sicher bist, bietet es sich an beim nächsten Club Treffen um Hilfe zu bitten. ;-)

Habe was geschrieben. Und nun?

Du kannst Deine Änderung einfach via git einchecken und anschließend in unseren gitlab Server pushen. Dadurch wird automatisch die entsprechende CI Pipeline gestartet, welche eine neue Version der FAQ veröffentlicht.