-
Notifications
You must be signed in to change notification settings - Fork 2
Leitfaden Handbuch
Aktuell wird das Benutzerhandbuch den Kunden über die Plattform "Read the Docs" bereitgestellt (http://hilfe.goalio.de/). Für künftige Änderungen am Handbuch selbst, soll dir dieser Leitfaden helfen.
Um zu verstehen wie das Handbuch strukturiert und organisiert wird, sollte man bestenfalls über grundlegende HTML-Kenntnisse verfügen. Andernfalls ist der Einstieg lediglich etwas holprig aber dennoch möglich. Die zu veröffentlichenden Dokumente werden in der Markup-Sprache reStructuredText (.rst) formuliert.
Die sichtbare Oberfläche des Handbuches gliedert sich in zwei Bereiche:
- Dokumentation
- Navigation (mit Drop-Down-Mechanik)
Die Dokumentation befindet sich auf der rechten Bildschirmhälfte und bildet alle zur Verfügung stehenden Inhalte ab, die wie oben erwähnt, in der Markup-Sprache reStructuredText formuliert werden.
Überschriften sorgen dafür, dass Textblöcke struktiert werden können. Gleichzeitig sorgen die Überschriften unterschiedlicher Ebenen für die spätere Darstellung der Navigationsstruktur auf der linken Seite der Bildschirmhälfte. Überschriften lassen sich wie folgt markieren:
============
Part title..
============
***************
Chapter title..
***************
Section title..
===============
Subsection title..
------------------
Subsubsection title..
^^^^^^^^^^^^^^^^^^^^^
FÜLLTEXT
Die Navigation findet sich auf der linken Bildschirmhälfte und lässt sich, je nach Einstellung, dynamisch auf- und zuklappen. Über Inhalt und Erscheinung der Navigation bestimmen die Index-Dateien (index.rst). Eine Index-Datei stellt immer die Haupt-/Startseite dar und wird über Befehle innerhalb der index-Datei mit anderen Unterseiten verknüpft. Stell dir einen Baum vor. Der Stamm bildet dabei die Index-Datei. Die Äste und Zweige bilden in dieser Veranschaulichung die Unter-Ebenen 1 und 2. Der Befehl um Seiten miteinander zu verknüpfen lautet:
.. toctree::
Beispielhafte Darstellung bei einer Navigation mit vier Hauptpunkten
.. toctree::
:hidden:
Mitglieder <module/mitglieder/index>
Abteilungen-und-Teams <module/abteilungen/index>
Finanzen <module/finanzen/index>
Statistiken <module/statistiken/index>
In diesem Beispiel verknüpft sich nun die Hauptseite mit den vier angegebenen Unterseiten, die wiederum mit anderen Unter-Unter-Seiten mittels des Befehls .. toctree:: miteinander verbunden werden können. Neben der Tatsache, dass nun eine direkte Referenz der Haupt-/Startseite zu seinen Unterseiten besteht, würde dieser Code die angegebene Struktur im Dokument selber zeigen - wäre da nicht der Befehl :hidden:. Dieser Befehl bewirkt, dass die Verzweigung in der Dokumentation nicht erscheint.
Die Schreibweise
Mitglieder <module/mitglieder/index>
sorgt dafür, dass in der Navigation die entsprechende Index-Datei mit dem Menüpunkt Mitglieder geführt wird. Solltest du nur den Pfad angeben, worüber die Index-Datei zu erreichen ist, wird der Menüpunkt automatisch so benannt, wie die Hauptüberschrift der Index-Datei lautet.
Möchtest du die Verzweigung/Navigation in der Dokumentation selber darstellen, aber nicht alle Unter-Ebenen zur Ansicht zur Verfügung stellen, nutzt du den Befehl :maxdepth: n. Das n steht dabei für die Anzahl der Ebenen, die noch dargestellt werden sollen.
Beispielhafte Darstellung fortgeführt
.. toctree::
:maxdepth: 2
Mitglieder <module/mitglieder/index>
Abteilungen-und-Teams <module/abteilungen/index>
Finanzen <module/finanzen/index>
Statistiken <module/statistiken/index>
Nun würden in der Dokumentation Alle Hauptmenüpunkte (Mitglieder, Abteilungen-und-Teams, Finanzen und Statistiken) in der Dokumentation selbst erscheinen. Zusätzlich deren 1. Unterebene.