| Sphinx |
| ====== |
| |
| Was ist Sphinx? |
| --------------- |
| |
| Sphinx ist ein Tool, welches Dokumentation aus Dateien im rST-Format |
| generiert. Also beispielsweise manpages, wie beispielsweise inzwischen |
| die Manpages fuer sefuns und lfuns. Also man schreibt alle Manpages im |
| rST-Format und dann kann Sphinx da alles draus machen, z.B. Manpages, |
| HTML-Seiten, PDFs, epubs etc. |
| |
| Das rST-Format ist dabei ein sogenanntes Markdownformat. Man schreibt |
| eigentlich alles so, wie man es auch in einem einfachen Text, also |
| beispielsweise dieser Manpage schreiben wuerde, und nur an Stellen, |
| welche besonders sein sollen, benutzt man mal gar nicht so komplizierte |
| Auszeichnungen. |
| |
| "Hm, kann ich nicht einfach meine Manpages wie vorher schreiben?" fragst |
| Du und eigentlich hast Du recht. Vorausgesetzt, Du hast Deine Manpages |
| vorher bereits einigermassen schoen formatiert, und die Ueberschrift der |
| Manpage beispielsweise mit einer Reihe Gleichheitszeichen, die |
| Unterueberschriften mit einer Reihe Minuszeichen abgetrennt, und alles |
| darunter ein bisschen und vor allem gleichmaessig eingerueckt. |
| |
| "Also schreibe ich meine Manpages, und dann roedelt da eine Maschine ewig |
| lange drueber und am Ende sieht es doch wieder genauso aus, wie es vorher |
| aussah?" Streng genommen. Muss man zugeben. Ja. Oder auch nicht. Die |
| Vorteile kriegen besser mal einen eigenen Abschnitt. |
| |
| |
| Vorteile von Sphinx |
| ------------------- |
| |
| - Dokumentation in verschiedenen Formaten verfuegbar, beispielsweise |
| findet man die schon in Sphinx ueberfuehrten Seiten in HTML formatiert |
| und durchsuchbar unter http://mg.mud.de/mglibdoc/ |
| -- hier profitiert man auch gut von den Verlinkungen. |
| |
| - es unterstuetzt Magier sich an ein paar wenige Regeln zu halten, welche |
| die Manpages auf jeden Fall uebersichtlicher halten. |
| |
| - fast gar kein Mehraufwand fuer den dokuschreibenden Magier; rST sieht |
| eigentlich genauso aus, wie man es eh schreiben wuerde, es gibt einem |
| nur noch weitere Mรถglichkeiten |
| |
| |
| Wo finde ich mehr ueber dieses Sphinx und rST? |
| ---------------------------------------------- |
| |
| Zunaechst sei angemerkt, dass rST ein ziemlich unspezifisches Format ist. |
| Generell empfiehlt es sich, nicht nur die Dokumentation zu rST zu lesen, |
| sondern auch ein paar Dateien im MorgenGrauen anzuschauen, die dann |
| zeigen, wie es schon konkret umgesetzt wurde; letztere fuehre ich |
| natuerlich auch auf: |
| |
| - http://www.sphinx-doc.org/en/stable/rest.html |
| die Sphinx-Dokumentation von diesem rST-Format |
| |
| - doc/sphinx |
| der Ort in der Mudlib, an dem die sphinx-Dateien landen |
| |
| - doc/sphinx/lfun/AddRoomMessage.rst, doc/sphinx/lfun/AddInfo.rst |
| doc/sphinx/lfun/RemoveExtraLook.rst, doc/sphinx/send_room.rst |
| Beispiele fuer Dateien die bereits in das rST-Format ueberfuehrt wurden |
| |
| - http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html -- |
| eine etwas ausfuehrlichere Referenz zu rST |
| |
| - http://www.sphinx-doc.org/ -- die Sphinx-Webseite |
| |
| |
| Hilfe, alle .rST-Files sind graesslich formatiert! |
| -------------------------------------------------- |
| |
| Derzeit sind die meisten noch automatisch durch ein Skript in das neue |
| Format ueberfuehrt worden. Das erkennt man daran, dass meistens direkt |
| nach der Ueberschrift ein :: folgt, und alles mit unzaehligen Spaces |
| eingerueckt ist. Da muesste jemand wirklich mal anpacken und das schoen |
| machen! |
| |
| > unt jemand |
| Du! |
| |
| Ausserdem ist noch gar nicht alles in Sphinx drin, aber zumindest |
| schonmal lfuns, efuns und PROPS. |
| |
| SIEHE AUCH |
| ---------- |
| |
| andere Dokumentationen zu Dokumentation und Workflow: |
| |
| wiz/man, wiz/gerrit, wiz/git, wiz/regionsleitfaden |
| concepts/goodstyle |
| |
| |
| Letzte Aenderung: 2018-02-01 von Deaddy |