| Deaddy | a902091 | 2018-02-01 09:41:20 +0100 | [diff] [blame] | 1 | Sphinx |
| 2 | ====== |
| 3 | |
| 4 | Was ist Sphinx? |
| 5 | --------------- |
| 6 | |
| 7 | Sphinx ist ein Tool, welches Dokumentation aus Dateien im rST-Format |
| 8 | generiert. Also beispielsweise manpages, wie beispielsweise inzwischen |
| 9 | die Manpages fuer sefuns und lfuns. Also man schreibt alle Manpages im |
| 10 | rST-Format und dann kann Sphinx da alles draus machen, z.B. Manpages, |
| 11 | HTML-Seiten, PDFs, epubs etc. |
| 12 | |
| 13 | Das rST-Format ist dabei ein sogenanntes Markdownformat. Man schreibt |
| 14 | eigentlich alles so, wie man es auch in einem einfachen Text, also |
| 15 | beispielsweise dieser Manpage schreiben wuerde, und nur an Stellen, |
| 16 | welche besonders sein sollen, benutzt man mal gar nicht so komplizierte |
| 17 | Auszeichnungen. |
| 18 | |
| 19 | "Hm, kann ich nicht einfach meine Manpages wie vorher schreiben?" fragst |
| 20 | Du und eigentlich hast Du recht. Vorausgesetzt, Du hast Deine Manpages |
| 21 | vorher bereits einigermassen schoen formatiert, und die Ueberschrift der |
| 22 | Manpage beispielsweise mit einer Reihe Gleichheitszeichen, die |
| 23 | Unterueberschriften mit einer Reihe Minuszeichen abgetrennt, und alles |
| 24 | darunter ein bisschen und vor allem gleichmaessig eingerueckt. |
| 25 | |
| 26 | "Also schreibe ich meine Manpages, und dann roedelt da eine Maschine ewig |
| 27 | lange drueber und am Ende sieht es doch wieder genauso aus, wie es vorher |
| 28 | aussah?" Streng genommen. Muss man zugeben. Ja. Oder auch nicht. Die |
| 29 | Vorteile kriegen besser mal einen eigenen Abschnitt. |
| 30 | |
| 31 | |
| 32 | Vorteile von Sphinx |
| 33 | ------------------- |
| 34 | |
| 35 | - Dokumentation in verschiedenen Formaten verfuegbar, beispielsweise |
| 36 | findet man die schon in Sphinx ueberfuehrten Seiten in HTML formatiert |
| 37 | und durchsuchbar unter http://mg.mud.de/mglibdoc/ |
| 38 | -- hier profitiert man auch gut von den Verlinkungen. |
| 39 | |
| 40 | - es unterstuetzt Magier sich an ein paar wenige Regeln zu halten, welche |
| 41 | die Manpages auf jeden Fall uebersichtlicher halten. |
| 42 | |
| 43 | - fast gar kein Mehraufwand fuer den dokuschreibenden Magier; rST sieht |
| 44 | eigentlich genauso aus, wie man es eh schreiben wuerde, es gibt einem |
| 45 | nur noch weitere Mรถglichkeiten |
| 46 | |
| 47 | |
| 48 | Wo finde ich mehr ueber dieses Sphinx und rST? |
| 49 | ---------------------------------------------- |
| 50 | |
| 51 | Zunaechst sei angemerkt, dass rST ein ziemlich unspezifisches Format ist. |
| 52 | Generell empfiehlt es sich, nicht nur die Dokumentation zu rST zu lesen, |
| 53 | sondern auch ein paar Dateien im MorgenGrauen anzuschauen, die dann |
| 54 | zeigen, wie es schon konkret umgesetzt wurde; letztere fuehre ich |
| 55 | natuerlich auch auf: |
| 56 | |
| 57 | - http://www.sphinx-doc.org/en/stable/rest.html |
| 58 | die Sphinx-Dokumentation von diesem rST-Format |
| 59 | |
| 60 | - doc/sphinx |
| 61 | der Ort in der Mudlib, an dem die sphinx-Dateien landen |
| 62 | |
| 63 | - doc/sphinx/lfun/AddRoomMessage.rst, doc/sphinx/lfun/AddInfo.rst |
| 64 | doc/sphinx/lfun/RemoveExtraLook.rst, doc/sphinx/send_room.rst |
| 65 | Beispiele fuer Dateien die bereits in das rST-Format ueberfuehrt wurden |
| 66 | |
| 67 | - http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html -- |
| 68 | eine etwas ausfuehrlichere Referenz zu rST |
| 69 | |
| 70 | - http://www.sphinx-doc.org/ -- die Sphinx-Webseite |
| 71 | |
| 72 | |
| 73 | Hilfe, alle .rST-Files sind graesslich formatiert! |
| 74 | -------------------------------------------------- |
| 75 | |
| 76 | Derzeit sind die meisten noch automatisch durch ein Skript in das neue |
| 77 | Format ueberfuehrt worden. Das erkennt man daran, dass meistens direkt |
| 78 | nach der Ueberschrift ein :: folgt, und alles mit unzaehligen Spaces |
| 79 | eingerueckt ist. Da muesste jemand wirklich mal anpacken und das schoen |
| 80 | machen! |
| 81 | |
| 82 | > unt jemand |
| 83 | Du! |
| 84 | |
| 85 | Ausserdem ist noch gar nicht alles in Sphinx drin, aber zumindest |
| 86 | schonmal lfuns, efuns und PROPS. |
| 87 | |
| 88 | SIEHE AUCH |
| 89 | ---------- |
| 90 | |
| 91 | andere Dokumentationen zu Dokumentation und Workflow: |
| 92 | |
| 93 | wiz/man, wiz/gerrit, wiz/git, wiz/regionsleitfaden |
| 94 | concepts/goodstyle |
| 95 | |
| 96 | |
| 97 | Letzte Aenderung: 2018-02-01 von Deaddy |