Comment lire la documentation de Django
Nous faisons le maximum pour obtenir une documentation de Django utile, facile à lire et aussi complète que possible. Voici quelques astuces pour en tirer le meilleur parti, accompagnées de quelques règles de mise en page.
(Oui, cette documentation est relative à la documentation. Soyez rassurés nous n'avons aucune intention d'écrire un document qui expliquera comment lire le document de la documentation.)
Comment la documentation est elle mise à jour
Tout comme le code de base de Django est développé et amélioré chaque jour, notre documentation s'améliore quotidiennement. Nous améliorons la documentation pour plusieurs raisons:
- Corriger les erreurs de contenu, tel que les erreurs de grammaires et de typographie
- Ajouter des informations et/ou des exemples aux sections existantes qui ont besoin d'être étendues
- Documenter les fonctionnalités de Django qui ne le sont pas encore. (La liste de ces fonctionnalités est en cours de diminution mais existe malgré tout.)
- Ajouter la documentation des nouvelles fonctionnalités lorsqu'elles sont ajoutées, ou lorsque les APIs ou comportements de Django évoluent.
La documentation de Django est gérée par le même système de gestion de version que son code source. Elle réside dans le répertoire django/trunk/docs de notre dépôt Subversion. Chaque document est un fichier texte séparé qui couvre un sujet bien défini, tel que le framework des "vues génériques" ou comment mettre en place un modèle de données.
Comment l'obtenir
Vous pouvez lire la documentation de Django de plusieurs manières. Les voici, par ordre de préférence:
Sur le Web
La version la plus récente de la documentation de Django réside à http://www.djangoproject.com/documentation/ . Ces pages HTML sont générées automatiquement à partir des fichiers textes du système de gestion de version. Ce qui implique qu'elles reflètent l'"ultime et le meilleur" dans Django -- elles incluent les toutes dernières corrections et ajouts, et parlent des dernières fonctionnalités, qui ne sont disponibles que pour les utilisateurs de la version en développement de Django. (Voir les "Differences entre versions" ci-dessous.)
Nous vous encourageons à améliorer les fichiers de documentation en envoyant vos modifications, corrections et autres suggestions via le système de ticket. Les développeurs de Django surveillent activement le système de ticket et utilisent vos retours pour améliorer la documentation pour tous.
Notez, cependant, que les tickets doivent faire explicitement référence à la documentation, au lieu de faire référence à une question de support technique d'ordre général. Si vous avez besoin d'aide pour votre propre installation de Django, essayez plutôt la liste de discussion django-users ou le canal IRC #django.
En texte plein
Pour une utilisation hors ligne, ou par simple commodité, vous pouvez lire la documentation de Django en texte plein.
Si vous utilisez une version officielle de Django, notez que la version zippée (tarball) du code inclut un répertoire docs/, qui contient toute la documentation de la version donnée.
Si vous utilisez la version en développement de Django (la branche "trunk" de Subversion), notez que le répertoire docs/ contient toute la documentation. Vous pouvez la svn update, tout comme vous svn update le code Python, afin d'obtenir les dernières mises à jour.
Vous pouvez récupérez la dernière version de la documentation de Django sur Subversion en utilisant cette ligne de commande:
svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs
Un moyen de base pour tirer parti de la documentation est d'utiliser l'utilitaire Unix grep pour rechercher une phrase dans toute la documentation. Par exemple, ce qui suit vous affichera toutes les occurrences de la phrase "edit_inline" apparaissant dans chaque fichier de documentation de Django:
grep edit_inline /chemin/vers/django/docs/*.txt
Formatage
Le texte de la documentation est rédigé dans le format ReST (texte ReStructuré). Ceci veut dire qu'il est facile à lire mais aussi qu'il est formaté de manière à ce qu'il soit facilement converti dans d'autres formats, tel que le HTML. Si vous avez la librairie reStructuredText installée, vous pouvez utiliser rst2html pour générer vos propres fichiers HTML.
Differences entre versions
Comme mentionné précédemment, le texte de la documentation de notre dépôt Subversion contient l'"ultime et le meilleur" des modifications et additions. Ces modifications incluent souvent la documentation de fonctionnalités ajoutées dans la version en développement de Django -- la version Subversion ("trunk") de Django. Pour cette raison, il est nécessaire d'exposer notre politique nous permettant de maintenir la documentation en bon état pour plusieurs versions du framework.
Nous suivons la politique suivante:
- La documentation principale sur djangoproject.com est une version HTML des dernières documentations dans Subversion. Ces fichiers correspondent toujours à la dernière version officielle de Django, plus quelques fonctionnalités que nous avons ajouté/modifié dans le framework depuis la dernière version.
- Lorsque nous ajoutons des fonctionnalités dans la version en développement de Django, nous essayons de mettre à jour la documentation dans la même transaction d'envoi à Subversion (commit).
- Pour distinguer les fonctionnalités d'ajout/modification dans les fichiers, nous utilisons la phrase Nouveau dans la version en développement de Django. En pratique, ceci implique que la version courante de la documentation sur djangoproject.com peut être utilisée indifféremment par les utilisateurs de la dernière version ou de la version en développement.
- La documentation d'une version donnée de Django est gelée dès que la version est officiellement sortie. Elle est une photo de l'état de la documentation au moment de la version. Nous ferons des exceptions à ces règles dans le cas de mises à jour de sécurité rétroactives ou tout autre modification rétroactive. Une fois la documentation gelée, nous ajoutons une note au début de chaque document gelé qui dit "Ces fichiers sont gelés pour la version XXX de Django" et des liens vers la version courante du fichier de documentation.
- La page Web d'accueil de la documentation inclut des liens vers la documentation des versions précédentes.