Wie man die Django-Dokumentation lesen sollte
Diese Dokumentation gilt für Djangos Entwicklerversion, die zum Teil erhebliche Unterschiede zur letzten veröffentlichen Version aufweist.
Wir haben viel Zeit investiert, die Dokumentation so nützlich, verständlich und vollständig wie möglich zu machen. Es folgen einige Tipps, wie man sie am besten benutzt und welche Richtlinien einzuhalten sind.
(Ja, das ist eine Dokumentation über die Dokumentation. Aber keine Angst, wir haben nicht vor zu erklären, wie man diese Seite zu lesen hat.)
Wie die Dokumentation auf dem Laufenden gehalten wird
Da der Code von Django quasi täglich weiterentwickelt und verbessert wird, entwickelt sich auch die Dokumentation ständig weiter. Wir verbessern die Dokumentation aus verschiedenen Gründen:
- Um inhaltliche Verbesserungen vorzunehmen, wie Grammatik- und Rechtschreibefehler.
- Um Informationen und/oder Beispiele zu schon existierenden Abschnitten hinzuzufügen, die erweitert müssen.
- Um Funktionen von Django zu dokumentieren, die noch keine Dokumentation haben. (Auch wenn die Liste immer kürzer wird, gibt es sie noch.)
- Um neue Funktionen zu dokumentieren, sobald sie eingebaut wurden oder wenn sich Djangos APIs ändern.
Djangos Dokumentation wird mit dem selben Verwaltungssystem gepflegt, wie der eigentliche Code. Es liegt im django/trunk/docs Verzeichnis unseres Subversion Repository. Jedes Dokument ist ein seperates Textdokument, das sich mit einem bestimmten Thema auseinandersetzt, wie z.B. mit dem “Generic Views” Framework oder wie man Datenmodelle entwirft.
Woher bekommen
Du kannst die Django-Dokumentation auf verschiedene Weise lesen. Das sind in sinnvoller Reihenfolge:
Im Internet
Die aktuellste Version der englischen Django-Dokumentation findet man unter http://www.djangoproject.com/documentation/ , die deutsche Variante unter http://www.django-de.org/documentation/ . Diese HTML-Seiten werden automatisch aus den Textdokumenten im Subversion Repository generiert und enthalten daher die letzten Änderungen und Neuigkeiten — also alle neuen oder verbesserten Funktionen von Django, die wahrscheinlich nur den Nutzern der Entwicklerversion zur Verfügung stehen. (Siehe unten “Unterschiede zwischen den Versionen.)
Wir freuen uns sehr, wenn du die Dokumentation durch Korrekturen und Vorschläge im Ticket System verbessern hilfst. Die Django-Entwickler achten aktiv auf das Ticket System und benutzen dein Feedback, um die Dokumentation zu verbessern.
Beachte aber bitte, dass sich die Tickets explizit auf die Dokumentation beziehen sollten, nicht auf technischen Fragen. Wenn du Hilfe bei einem bestimmten Django Problem brauchst, schau bitte in der Django-users (englisch) und Django-de Mailingliste oder den IRC Channel #django (englisch) und #django-de (deutsch) vorbei.
In Textdokumenten
Wenn du gerade einmal keinen Zugang zum Internet hast oder es einfach für praktischer hälst, kannst du die Django-Dokumentation auch direkt als Textdokument lesen.
Wenn du eine offzielle Version von Django benutzt, schau dir bitte das in der komprimierten Datei (tar.gz oder zip) enthaltene docs/ Verzeichis an — es enthält die gesamte Dokumentation für diese Version.
Wenn du die Entwicklerversion von Django benutzt (auch Subversion “trunk” genannt), sieh dir bitte das docs/ Verzeichnis an — es enthält die gesamte Dokumentation. Du kannst auf dem Laufenden bleiben, in dem du einfach, wie beim Python Code von Django, svn update im docs/ Verzeichnis ausführst.
Du kannst die aktuelle Version der Dokumentation mit folgendem Befehl aus dem Subversion auschecken:
svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs
Eine Möglichkeit, die Textdokumente der Dokumentation einfach zu nutzen, ist der Einsatz des Unix Utility grep. Damit kann man die gesamte Dokumentation nach einem bestimmten Begriff durchsuchen, zum Beispiel “edit_inline”:
grep edit_inline /path/to/django/docs/*.txt
Formatierung
Die Textdokumentation ist in ReST Syntax (ReStructured Text) geschrieben. Es ist damit einerseits einfach zu lesen und andererseits so formatiert, dass es einfach in andere Formate (wie z.B. HTML) konvertiert werden kann. Wenn du die reStructuredText Bibliothek installiert hast, kannst du rst2html benutzen, um eigene HTML-Dateien zu generieren.
Unterschiede zwischen den Versionen
Wie schon erwähnt, enthält die Dokumentation im Subversion Repository die letzten Änderungen und Neuigkeiten. Diese Änderungen betreffen oft komplett neue Features, die in die Entwicklerversion hinzugefügt wurden — der Subversion (“trunk”) Version von Django. Deshalb sei hier erwähnt, warum wir die Versionen der Dokumentation so strikt trennen.
Wir verfolgen diese Strategie:
- Die Haupt-Dokumentation auf djangoproject.com ist eine HTML Version der aktuellsten Dokumentation im Subversion Repository. Diese Dokumentation wird immer mit der letzten offziellen Version von Django übereinstimmen, plus derjenigen Features, die nach der letzten Veröffentlichung hinzugefügt oder verändert worden.
- Sobald wir neue Features zu Djangos Entwicklerversion hinzufügen, versuchen wir auch eine Dokumentation des Features hinzuzufügen.
- Um Funktionsänderungen in der Dokumentation zu kennzeichnen, benutzen wir den Satz Neu in Djangos Entwicklerversion. Dadurch kann die Dokumentation von Nutzern der zuletzt veröffentlichten Version oder von Nutzern der Entwicklerversion von Django genutzt werden.
- Die Dokumentation für eine bestimmte Version wird abgetrennt, sobald sie offziell veröffentlicht wurde. Ein Schnapschuss der Dokumentation bleibt bei Veröffentlichung erhalten. Die einzige Ausnahme für diese Regel sind Änderungen aus Sicherheits- oder anderen zwingenden Gründen. Wenn eine Dokumentationsversion abgetrennt wurde, fügen wir oben den Hinweis “Diese Dokumentation gilt für die Django-Version XXX” und verweisen auf die aktuelle Version der Dokumentation.
- Die Hauptseite der Dokumentation enthält Links zu den Dokumentationen aller vorherigen Versionen.