Quelle lecture pour la suite

Vous avez donc lu toute la documentation d’introduction et vous avez décidé de continuer à utiliser Django. Nous n’avons fait qu’effleurer la surface dans cette introduction (même en ayant lu chaque mot de l’introduction, vous n’avez parcouru qu’environ 5 % de toute la documentation).

Comment continuer ?

Nous avons toujours été partisans de l’apprentissage par l’action. À ce stade, vous devriez en savoir assez pour commencer votre propre projet en explorant la technologie. Dès que vous ressentez le besoin d’apprendre de nouveaux concepts, revenez à la documentation.

Nous avons consacré beaucoup d’énergie pour rendre la documentation de Django utile, facile à lire et aussi complète que possible. La suite de ce document explique un peu plus comment est structurée cette documentation afin que vous puissiez en tirer le meilleur parti.

(Oui, c’est une documentation sur la documentation. Soyez assuré que nous n’avons aucun projet d’écrire un document sur la manière de lire le document au sujet de la documentation.)

Recherche dans la documentation

La documentation de Django est volumineuse (presque 450 000 mots), il est donc parfois périlleux de trouver ce que l’on cherche. Deux bons points de départs sont la Page de recherche et l’Index.

Ou vous pouvez tout aussi bien naviguer dans les contenus.

Organisation de la documentation

La documentation principale de Django est segmentée en sections prévues pour répondre à différents besoins :

• Le contenu d’introduction est conçu pour les débutants avec Django, ou avec le développement Web en général. Il ne traite pas de tout en détails, mais donne plutôt un aperçu de haut niveau sur l’approche générale du développement en Django.

• Les guides thématiques, d’un autre côté, traitent en profondeur de domaines spécifiques de Django. Il existe des guides complets sur le système des modèles, le moteur de gabarits, l’architecture des formulaires, et bien plus encore.

  C’est probablement l’endroit où vous passerez le plus de temps ; si vous faites l’effort de parcourir ces différents guides, vous connaîtrez presque tout ce qu’il y a à savoir sur Django.

• Le développement Web est à large spectre, mais pas profond (les problématiques recouvrent de nombreux domaines). Nous avons rédigé un ensemble de marches à suivre qui répondent aux « Comment dois-je faire pour... ? » les plus courants. Vous trouverez là des informations sur la génération de PDF avec Django, l’écriture de balises de gabarits personnalisées, et d’autres sujets encore.

  Les réponses aux questions vraiment très souvent posées peuvent aussi être trouvées dans la FAQ.

• Les guides et les marches à suivre ne traitent pas de chaque classe, fonction ou méthode disponible dans Django, car ce serait décourageant pour ceux qui cherchent à apprendre. Par contre, tous les détails sur les classes, fonctions, méthodes et modules sont donnés dans la référence. C’est là que vous devrez chercher pour obtenir des détails sur une fonction particulière ou tout autre objet.

• Si vous êtes intéressé à déployer un projet publiquement, notre documentation contient quelques guides présentant diverses stratégies de déploiement ainsi qu’une liste de contrôle de déploiement pour vous rendre attentifs à certains aspects importants.

• Pour finir, il existe aussi une documentation « spécialisée » qui n’est habituellement pas destinée à la majorité des développeurs. Ceci inclut les notes de publication et de la documentation interne pour ceux qui se destinent à ajouter du code dans Django lui-même, ainsi que quelques autres documents qui n’entrent dans aucune autre catégorie.

Mise à jour de la documentation

Tout comme le code Django est développé et amélioré chaque jour, cette documentation s’améliore aussi constamment. Nous améliorons la documentation pour plusieurs raisons :

• Pour corriger des contenus, comme des corrections grammaticales et orthographiques.

• Pour ajouter des informations ou des exemples dans des sections existantes mais qui ont besoin d’être complétées.

• Pour documenter des fonctionnalités Django qui ne figurent pas encore dans la documentation (la liste des éléments concernés diminue, mais il y en a encore).

• Pour ajouter de la documentation pour de nouvelles fonctions lorsqu’elles sont ajoutées, ou quand l’API ou le comportement de Django est modifié.

La documentation de Django est conservée dans le même système de gestion de version que le code. Elle se trouve dans le répertoire docs de notre dépôt Git. Chaque page de cette documentation est un fichier texte distinct dans le dépôt.

Où 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 se trouve à l’adresse https://docs.djangoproject.com/en/dev/. Ces pages HTML sont générées automatiquement à partir des fichiers texte dans le gestionnaire de versions. Cela signifie qu’elles reflètent la toute dernière version de Django, comprenant les toutes dernières corrections et ajouts, et qu’elles abordent les fonctionnalités les plus récentes de Django, qui ne sont parfois disponibles que pour ceux qui utilisent la version de développement de Django (voir « Différences entre versions » ci-dessous).

Nous vous encourageons à aider à l’amélioration de la documentation en proposant des modifications, des corrections et des suggestions dans le système de tickets. Les développeurs Django surveillent de façon attentive le système de tickets et exploitent vos contributions afin d’améliorer la documentation au profit de tous.

Notez toutefois que les tickets doivent être liés explicitement à la documentation, et non pas à des questions d’aide de portée générale. Si vous avez besoin d’aide avec une configuration particulière de Django, adressez-vous plutôt aux canaux d’aide appropriés (liste de diffusion |django-users| ou `canal IRC #django).

En mode texte

Pour une lecture hors ligne ou simplement par préférence, il est possible de lire la documentation de Django en mode texte pur.

Si vous utilisez une version officielle de Django, le paquet compressé du code contient un répertoire docs/ comprenant toute la documentation correspondant à cette version.

Si vous utilisez la version de développement de Django (« trunk »), notez que le répertoire docs/ contient toute la documentation. Vous pouvez mettre à jour votre extraction Git pour obtenir les dernières modifications.

Une astuce pratique pour exploiter la documentation brute de Django est d’utiliser l’utilitaire Unix « grep » pour rechercher du contenu dans toute la documentation. Par exemple, ceci vous indiquera toutes les mentions de l’expression « max_length » dans la documentation :

$ grep -r max_length /path/to/django/docs/

En HTML, localement

Vous pouvez produire une version locale de la documentation HTML en suivant ces quelques étapes :

• La documentation de Django utilise un système appelé Sphinx pour convertir le texte brut en HTML. Vous devez donc installer Sphinx soit en le téléchargeant et en installant le paquet à partir du site Web de Sphinx, ou à l’aide de pip :

  $ pip install Sphinx
  

• Puis, il suffit d’utiliser le fichier Makefile inclus pour transformer la documentation en HTML :

  $ cd path/to/django/docs
  $ make html
  

  GNU Make doit être installé pour que ça fonctionne.

  Si vous êtes sur Windows, il est aussi possible d’utiliser le fichier batch inclus :

  cd path\to\django\docs
  make.bat html
  

• La documentation HTML sera placée dans docs/_build/html.

Note

La génération de la documentation Django fonctionne avec toute version de Sphinx à partir de la 0.6, mais nous recommandons d’utiliser la version 1.0.2 ou plus récente de Sphinx.

Différences entre versions

Comme mentionné précédemment, la documentation au format texte dans le dépôt Git contient toutes les modifications les plus récentes. Ces modifications comprennent souvent de la documentation sur des nouvelles fonctionnalités ajoutées dans la version de développement de Django (la version dite « trunk »). Pour cette raison, il est utile d’expliquer notre politique de conservation de la documentation spécifique pour chaque version de Django.

Nous appliquons la politique suivante :

• La documentation principale sur le site djangoproject.com est une version HTML de la toute dernière version dans Git. Cette documentation correspond toujours à la dernière version officielle de Django, augmentée de toutes les fonctionnalités ajoutées ou modifiées depuis la dernière publication.

• Au rythme de l’ajout de fonctionnalités dans la version de développement de DJango, nous essayons de mettre à jour la documentation dans la même transaction Git que les modifications de code.

• Pour mettre en évidence les modifications ou ajouts de fonctionnalités dans la documentation, nous utilisons la phrase « New in version X.Y », où X.Y correspond à la prochain version qui sera publiée (donc celle qui est en cours de développement).

• Les corrections et améliorations de documentation peuvent être reportées dans la branche de la version stable, selon l’appréciation de la personne chargée du commit. Cependant, dès qu’une version de Django n’est plus prise en charge, cette version de la documentation n’est plus mise à jour.

• La page Web principale de la documentation contient des liens vers la documentation de toutes les versions précédentes. Prenez soin de bien utiliser la version de la documentation qui correspond à la version de Django que vous utilisez !