================

Que lire ensuite

================

Ainsi donc vous avez lu toute l':ref:`introduction <intro-index>` et avez

décidé de continuer à utiliser Django. Nous n'avons fait que survoler le sujet

dans cette introduction (en fait, si vous avez lu chaque mot de cette

introduction, cela ne constitue que 10% de la documentation).

Et après ?

Nous avons toujours été des adeptes de l'apprentissage par la pratique. Pour

l'instant vous devriez en savoir assez pour commencer un projet de vous-même

et faire votre cuisine. Lorsque vous avez besoin d'apprendre de nouvelles

choses, revenez voir la documentation.

Nous avons fait de gros efforts pour rendre la documentation de Django utile,

facile à lire et aussi complète que possible. Le reste de ce document donne

des détails sur la manière dont fonctionne la documentation pour que vous en

tiriez le meilleur parti.

(Oui oui, il s'agit de documentation sur la documentation. Soyez assurés que

nous ne prévoyons pas d'écrire un document expliquant comment lire le document

expliquant la documentation.)

Trouver la documentation

========================

Django dispose de *beaucoup* de documentation -- presque 200 000 mots -- et

trouver ce dont vous avez besoin peut devenir un peu retors. :ref:`search` et

:ref:`genindex` sont des bons endroit pour commencer.

Ou alors, vous n'avez qu'à naviguer !

Organisation de la documentation

================================

La documentation principale de Django est séparée en "gros morceaux" destinés

à subvenir à différents besoins :

    * L':ref:`introduction <intro-index>` est destinée aux personnes qui

      débutent avec Django -- ou avec le développement Web de manière

      générale. Rien n'est détaillé en profondeur, mais on y trouve un aperçu

      de haut niveau sur la manière de développer avec Django

    * Les :ref:`guides thématiques <topics-index>` plongent plus profondément

      dans des parties précises de Django. Il y a des guides complets pour le

      :ref:`système de modèles <topics-db-index>`, le :ref:`moteur de

      template <topics-templates>`, le :ref:`framework de formulaires

      <topics-forms-index>`, et bien plus encore.

      C'est probablement là que vous passerez le plus de temps ; si vous

      vous allez voir ces guides, vous devriez connaître à peu près tout ce

      qu'il y a à savoir sur Django.

    * Le développement Web est un domaine large, les problèmes couvrent

      plusieurs domaines. Nous avons écrit un assortiment de ":ref:`how-to

      guides <howto-index>`" qui répondent aux questions rcurrentes du type

      "Comment est-ce que... ? Vous trouverez aussi des informations sur la

      :ref:`génération de PDFs avec Django <howto-outputting-pdf>`, sur

      l':ref:`écriture de balises de template personnalisées

      <howto-custom-template-tags>`, et plus encore.

      Les réponses aux questions très courantes se situent dans la :ref:`FAQ

      <faq-index>`.

    * Les guides et "how-to's" ne couvrent pas chaque classe, fonction et

      méthode disponible sous Django -- ce serait un peu écrasant lorsqu'on

      essaye d'apprendre. En revanche, les détails sur les classes, fonctions

      et méthodes sont rangés dans la partie :ref:`reference <ref-index>`.

      C'est ici que vous trouverez les détails d'une fonction donnée ou je ne

      sais quoi.

    * Enfin, il reste de la documentation "spécialisée" qui n'est en général

      pas pertinente pour la plupart des développeurs. Ceci inclut les

      :ref:`notes de version <releases-index>`, la :ref:`documentation des

      fonctionnalités obsolètes <obsolete-index>`, la :ref:`documentation

      interne <internals-index>` pour ceux qui veulent contribuer à Django

      lui-même, ainsi qu':ref:`un certain nombre d'autres choses qui ne

      peuvent pas être rangées autre part <misc-index>`.

Mise à jour de la documentation

===============================

Tout comme le code de Django est développé et amélioré quotidiennement, notre

documentation s'améliore en continu. Nous améliorons la documentation pour

plusieurs raisons :

    * Pour corriger des problèmes de contenu, comme des questions de grammaire

      ou de typographie.

    * Pour ajouter des informations et/ou des exemples à des parties qui ont

      besoin d'être plus détaillées.

    * Pour documenter des fonctionnalités de Django qui ne le sont pas encore.

      (la liste de ces fonctionnalités rétrécit mais existe malgré tout.)

    * Pour ajouter de la documentation sur des nouvelles fonctionnalités au

      fur et à mesure de leur ajout, ou lorsque les APIs ou comportements de

      Django changent.

La documentation de Django est située dans le même système de contrôle de

source que le code. Elle est située dans le dossier `django/trunk/docs`_ de

notre dépôt subversion. Chaque document en ligne est un fichier texte sur le

dépôt.

.. _django/trunk/docs: http://code.djangoproject.com/browser/django/trunk/docs

Où la trouver

=============

Vous pouvez lire la documentation de Django sous plusieurs formes. Les voici,

par ordre de préférence :

Sur internet

------------

La version la plus récente de la documentation de Django est sur

http://docs.djangoproject.com/en/dev/. Ces pages HTML sont générées

automatiquement depuis les fichiers texte du dépôt. Cela signifie qu'elles

reflètent ce qu'il y a de mieux et de plus récent dans Django -- elles

comprennent les toutes dernières corrections et ajouts, et elles parlent des

dernières fonctionnalités de Django, qui ne sont disponibles que pour les

utilisateurs disposant de la dernière version de développement de Django.

(voir ci-dessous, "Différences entre les versions")

Nous vous encourageons à améliorer la documentation en envoyant des

modifications, des corrections et des suggestions dans le "`ticket system`_".

Les développeurs de Django suivent activement le "ticket system" et améliorent

la documentation pour tous grâce à votre retour d'information.

Notez, cependant, que les tickets doivent être liés explicitement à la

documentation, plutôt que de poser des questions de support technique très

larges. Si vous avez besoin d'aide avec votre installation de Django, essayez

plutôt la `mailing-liste des utilisateurs de Django`_ ou le `channel IRC

#django`_.

.. _ticket system: http://code.djangoproject.com/simpleticket?component=Documentation

.. _mailing-liste des utilisateurs de Django: http://groups.google.com/group/django-users

.. _channel IRC #django: irc://irc.freenode.net/django

En texte brut

-------------

Pour lire hors-ligne, ou juste par commodité, vous pouvez lire la

documentation de Django en texte brut.

Si vous utilisez une version officielle de Django, notez que le paquet zippé

(tarball) du code inclut un répertoire ``docs/``, qui contient toute la

documentation de cette version.

Si vous utilisez la version de développement de Django (le "trunk" de

Subversion), notez que le répertoire ``docs/`` contient toute la

documentation. Vous pouvez la ``svn update``, tout comme vous ``svn

update``-ez le code Python, pour récupérer les dernières modifications.

Vous pouvez télécharger la dernière version de la documentation de Django

grâce à cette commande shell :

.. code-block:: bash

    $ svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs

Notre moyen à nous de tirer parti de la documentation en format texte est

d'utiliser l'utilitaire Unix ``grep`` pour chercher une expression dans toute

la documentation. Par exemple, voici comment trouver chaque mention de

l'expression "max_length" dans n'importe quel document :

.. code-block:: bash

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

En HTML, localement

-------------------

Vous pouvez récupérer en local une copie de la documentation HTML en suivant

ces étapes simples :

    * la documentation de Django utilise un système appelé Sphinx__ pour

      convertir du texte brut à l'HTML. Vous aurez besoin d'installer Syphinx,

      soit en téléchargeant et installant le paquet depuis le site de Sphinx,

      ou en utilisant ``easy_install`` :

      .. code-block:: bash

          $ easy_install Sphinx

    * Puis utilisez simplement le ``Makefile`` pour transformer la

      documentation en HTML :

      .. code-block:: bash

          $ cd path/to/django/docs

          $ make html

      Vous aurez besoin de `GNU Make`__ pour cela.

    * La documentation HTML se trouve dans ``docs/_build/html``.

.. warning::

    À l'heure où ce document est écrit, Django utilise une version de Sphinx

    qui n'a pas encore été publiée, vous devez donc installer Sphinx depuis

    les sources. Nous résoudrons cela rapidement.

__ http://sphinx.pocoo.org/

__ http://www.gnu.org/software/make/

Différences entre les versions

==============================

Comme écrit précédemment, la documentation en texte de notre dépôt Subversion

contient les changements les "meilleurs et les plus récents". Ces changements

comprennent souvent de la documentation ou des nouvelles fonctionnalités

ajoutées dans la version de développement de Django -- la version "trunk" de

Django. Pour cette raison, il est important d'insister sur le fait que nous

nous efforçons de garder la documentation fiable pour plusieurs versions du

framework.

Nous suivons cette politique :

    * La documentation principale sur djangoproject.com est une version HTML

      de la dernière documentation du dépôt subversion. La documentation

      correspond toujours à la dernière version officielle de Django, plus

      toutes les fonctionnalités que nous avons changé ou ajouté dans le

      framework *depuis* la dernière version.

    * Au fur et à mesure que nous ajoutons des fonctionnalités à la version de

      développement de Django, nous essayons de mettre à jour la documentation

      dans le même commit.

    * Pour différencier les changements de fonctionnalités des ajouts de

      fonctionnalités, nous utilisons l'expression "Nouveau dans la version

      X.Y", avec X.Y la prochaine version (et donc celle qui est développée).

    * La documentation pour une version de Django donnée est gelée une fois

      que la version a été publiée officiellement. Il ne subsiste qu'un

      instantané de la documentation au moment de la sortie. Nous ferons des

      exceptions à cette règle dans le cas de mises à jour de sécurité

      rétroactives ou dans le cas d'autres changements rétroactifs. Une fois

      que la documentation est gelée, nous ajoutons une note en haut de chaque

      document gelé annonçant "Cette documentation est gelée pour la version

      de Django XXX" et qui permet d'accéder à la version actuelle du

      document.

    * La `page d'accueil de la documentation`_ contient des liens vers la

      documentation de toutes les versions précédentes.

.. _page d'accueil de la documentation: http://docs.djangoproject.com/en/dev/