.. _service-faq: Über diese FAQ ############## .. toctree:: :maxdepth: 2 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. .. _faq-constibute: 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. .. _faq-howthe: 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. .. tip:: 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. .. _faq-miniexample: Minimalbeispiel =============== .. code-block:: rst .. _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. .. _faq-localpreview: 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: .. code-block:: bash sphinx-build -a -b html -d _build/doctrees . _build/html .. tip:: Falls Du dir nicht sicher bist, bietet es sich an beim nächsten Club Treffen um Hilfe zu bitten. ;-) .. _faq-remotehow: 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.