Eine Dokumentation zu schreiben ist jede Menge Arbeit. Hilfe dabei ist daher gerne gesehen.
Der Quellcode diese Dokumentation befindet sich auf Github: Meshkit Dokumentation.
Zur Erstellung der Dokumentation wird Sphinx genutzt.
Viele Linux Distributionen bieten Sphinx als Paket an, unter Debian kann es installiert werden mit:
aptitude install python-sphinx python-pygments
Desweiteren benötigt diese Dokumentation ein angepasstes Theme, das mit folgendem Befehl installiert werden kann:
easy_install sphinxjp.themes.basicstrap
oder alternativ mit
pip install sphinxjp.themes.basicstrap
Überschriften sollen Texte logisch Gliedern. Mehr als 4 Ebenen sind in der Regel nicht sinnvoll.
| Level | Unterstreichen mit |
|---|---|
| 1 (Kapitelüberschriften) | = |
| 2 | = |
| 3 | - |
| 4 | ^ |
Codeblöcke immer kennzeichnen mit
.. code-block:: sh
while true; do
ping -n 3 google.de
done
was dann so aussieht:
while true; do
ping -n 3 google.de
done
Auch hierfür gibt es ein Label:
:guilabel:`Irgendwas in der GUI`
was dann so aussieht:
Irgendwas in der GUI
Pfade zu Dateien und Verzeichnissen werden durch das Label :file: kenntlich gemacht, z.B.
:file:`/etc/passwd`
was dann so aussieht:
/etc/passwd
Kommandos auf der Shell sollten durch das Label :command: kenntlich gemacht werden, z.B.
:command:`/etc/init.d/olsrd restart`
was dann so aussieht:
/etc/init.d/olsrd restart
Abkürzungen wie z.B. DHCP sollten im Glossar (glossar.rst) erklärt werden. Um Begriff dann auf die entsprechende Stelle im Glossar zu verlinken wird :term: verwendet, z.B.
Foo kann mit :term:`DHCP` konfiguriert werden
Das sieht im Text dann so aus:
Foo kann mit DHCP konfiguriert werden
Um auch im PDF definierte tabellenbreiten zu haben, müssen diese in absoluten Werten angegeben werde. Die Gesamtbreite der Tabelle darf dabei maximal 15cm sein.
Beispiel für eine Tabelle mit 2 Spalten:
.. tabularcolumns:: |p{6cm}|p{9cm}|
Dies direkt vor der Definition der Tabelle in der .rst Datei einfügen.