Hi, ich meine mich zu erinnern, dass es PEP8 mal in deutscher Übersetzung gab? Habe aber keinen Link und nur eine leere Seite finden können!?
Ich habe mir gerade docs.python.org angesehen, gibt es dazu eine Vorgabe, wie die Software-Dokumentation aussehen soll? Ich habe einige Module, die ich immer mal wieder nutze und dann ggf. auch umschreibe. Ich mache mir da irgendwie Notizen; eine gute Dokumentation wäre aber m. E. besser und Vorgaben würden es mir erleichtern (btw: Ich möchte mich aktuell nicht in zugehörige Tools einarbeiten. Ich befürchte, dass mir dazu die Zeit fehlt...)
PEP8 in deutscher Übersetzung? Software-Dokumentation?
-
BlackJack
@pixewakb: Das Wiki war zwischenzeitlich ja mal weg. Nur gut das im Internet so viel archiviert wird: http://web.archive.org/web/201312082017 ... PEP%208%20(%C3%9Cbersetzung%29
Wie willst Du denn die Dokumentation ohne die dazugehörigen Werkzeuge erstellen?
Wie willst Du denn die Dokumentation ohne die dazugehörigen Werkzeuge erstellen?
Ich habe ein MediaWiki, wo ich ohnehin mit arbeiten muss und dort kann ich - zunächst für mich - den Quellcode dokumentieren. Das wäre dann für mich auch einfacher, als einige weitere HTML-Seiten irgendwie nebenher.
Ich habe z. B. so etwas hier gefunden: https://docs.python.org/3/library/sched.html
Für mich ist die Frage, ob dem ein Konzept zugrunde liegt, was ich einfach irgendwo nachlesen kann, weil ich sonst wahrscheinlich Gefahr laufe das Rad immer wieder neu zu erfinden.
Ich habe z. B. so etwas hier gefunden: https://docs.python.org/3/library/sched.html
Für mich ist die Frage, ob dem ein Konzept zugrunde liegt, was ich einfach irgendwo nachlesen kann, weil ich sonst wahrscheinlich Gefahr laufe das Rad immer wieder neu zu erfinden.
-
BlackJack
@pixewakb: Den Quelltext dokumentiert man üblicherweise im Quelltext selber. Ich denke mal Du meinst die API. Das kann man natürlich in einem Wiki machen.
Ich weiss nicht ob ich die Frage nach dem Link zur Standarddokumentation richtig verstehe. Die ist mit Sphinx erstellt, also mit Texten die in reStructuredText + Sphinx-Erweiterungen ausgezeichnet sind. Daraus kann man dann eine HTML-Dokumentation generieren lassen, aber auch andere Formate wie PDF (über LaTeX) oder E-Books im ePub-Format. Wie das aussieht was man dafür schreiben muss kann man sich bei der Python-Dokumentation ja anschauen weil die Seiten einen Link zu der dazugehörigen Quelltextdatei haben. Für Deine Beispielseite führt der Link beispielsweise hier hin: https://docs.python.org/3/_sources/library/sched.txt
Klar muss man die Auszeichnung für Sphinx erst einmal lernen, aber die bietet dann auch Vorteile, zum Beispiel das man die einzelnen Bestandteile wie Attribute, Funktionen, Klassen, und Methoden als solche markieren und einfach referenzieren kann und automatisch ein Index erstellt wird. Ein Glossar kann man ebenso leicht anlegen.
Ich weiss nicht ob das bei der Standardbibliothek irgendwo gemacht wird, aber man kann auch Docstrings aus dem Quelltext in die API-Dokumentation ziehen um sich doppeltes dokumentieren zu ersparen.
Ich weiss nicht ob ich die Frage nach dem Link zur Standarddokumentation richtig verstehe. Die ist mit Sphinx erstellt, also mit Texten die in reStructuredText + Sphinx-Erweiterungen ausgezeichnet sind. Daraus kann man dann eine HTML-Dokumentation generieren lassen, aber auch andere Formate wie PDF (über LaTeX) oder E-Books im ePub-Format. Wie das aussieht was man dafür schreiben muss kann man sich bei der Python-Dokumentation ja anschauen weil die Seiten einen Link zu der dazugehörigen Quelltextdatei haben. Für Deine Beispielseite führt der Link beispielsweise hier hin: https://docs.python.org/3/_sources/library/sched.txt
Klar muss man die Auszeichnung für Sphinx erst einmal lernen, aber die bietet dann auch Vorteile, zum Beispiel das man die einzelnen Bestandteile wie Attribute, Funktionen, Klassen, und Methoden als solche markieren und einfach referenzieren kann und automatisch ein Index erstellt wird. Ein Glossar kann man ebenso leicht anlegen.
Ich weiss nicht ob das bei der Standardbibliothek irgendwo gemacht wird, aber man kann auch Docstrings aus dem Quelltext in die API-Dokumentation ziehen um sich doppeltes dokumentieren zu ersparen.