Source

djangofrdoc / intro / whatsnext.txt

Full commit
========================
Ce qu'il faut lire après
========================

Vous avez lu toute l':doc:`introduction </intro/index>` et vous avez décidé
d'adopter Django. Cette introduction n'a fait que brosser la surface (celle-ci ne
représente pas plus de 10% de la documentation).

Quelle est la suite ?

Et bien, nous avons toujours été fans de l'apprentissage par la pratique.
Arrivés la, vous devriez avoir le bagage suffisant pour commencer votre propre
projet et vous amuser avec. Lorsque vous aurez à apprendre de nouvelles astuces,
retournez à la documentation.

Nous nous sommes efforcés de faire de la documentation de Django une
documentation utile, facile à lire et la plus complète possible. La suite de ce
document explique comment fonctionne la documentation pour que vous en tiriez un
maximum de profit.

(Et oui, ce document traite de la documentation. Rassurez-vous, il n'y aura pas
de document expliquant comment lire le document au sujet de la documentation.)

Trouver la documentation
========================

Django a *beaucoup* de documentation -- environ 200 000 mots --; trouver ce que
vous recherchez peut donc paraître compliqué. Deux bons points de départ sont
:ref:`search` et :ref:`genindex`.

Vous pouvez aussi simplement parcourir la documentation!

Comment est organisée la documentation?
=======================================

La documentation de Django est répartie de manière à répondre à différents
besoins:

    * L':doc:`introduction </intro/index>` est conçue pour les personnes
      débutant Django -- ou le développement Web de manière générale. Les sujets
      n'y sont pas traités en profondeur pour permettre de décrire à quoi
      "ressemble" le développement avec Django en proposant une vue globale.

    * Les :doc:`guides par sujet </topics/index>`, quant à eux, traitent des
      différentes composantes de Django de manière beaucoup plus exhaustive. Des
      guides complets couvrent les :doc:`modèles et bases de données
      </topics/db/index>`, le :doc:`moteur de template</topics/templates>`, le
      :doc:`framework de formulaires</topics/forms/index>`, et bien plus encore.
      
      C'est probablement la partie qui mérite le plus votre attention; si vous
      suivez ces guides, vous devriez en ressortir en sachant à peu près tout
      ce qu'il y a à savoir au sujet de Django.

    * Le développement Web est souvent "large", mais peu profond -- les problèmes
      rencontrés couvrant une multitude de domaines. Nous avons écrit un
      ensemble de :doc:`guides how-to </howto/index>` qui répondent aux questions
      du type "Comment puis-je... ?" les plus communément posées. Vous y
      trouverez des informations pour :doc:`générer des PDFs avec Django
      </howto/outputting-pdf>`, :doc:`écrire vos propres template tags
      </howto/custom-template-tags>`, et plus encore.

      Les réponses aux questions les plus fréquentes sont aussi disponibles dans
      la :doc:`FAQ </faq/index>`.

    * Les guides et how-to's ne couvrent pas chacune des classes, fonctions et
      méthodes disponibles dans Django -- ce serait trop lourd lors de
      l'apprentissage. La documentation des classes, fonctions, méthodes et
      modules est couverte dans la :doc:`référence </ref/index>`. C'est ici
      que vous trouverez les détails d'une fonction particulière.

    * Enfin, il y a une documentation "spécialisée" qui peut ne pas paraître
      pertinente à tous les développeurs. Celle-ci inclut les :doc:`notes de
      version </releases/index>`, la :doc:`documentation des fonctionnalités
      obsolètes </obsolete/index>`, la :doc:`documentation interne
      </internals/index>` pour ceux qui souhaiteraient ajouter du code à Django,
      ainsi que :doc:`certains sujets qui n'ont pas leur place ailleurs
      </misc/index>`.

Comment est mise à jour la documentation
========================================

Au même titre que le code de Django est développé est amélioré quotidiennement,
la documentation s'améliore aussi. Nous l'améliorons pour plusieurs raisons:

    * Pour corriger le contenu, comme les fautes de grammaire et d'orthographe.
    
    * Pour ajouter des informations et/ou des exemples à des sections existantes
      nécessitant plus de détails.
    
    * Pour documenter des fonctionnalités de Django qui ne le sont pas encore.
      (La liste de ces fonctionnalités tend à réduire mais existe bel et bien.)
    
    * Pour ajouter la documentation des nouvelles fonctionnalités lorsqu'elles
      sont ajoutées, ou lorsque les APIs de Django ou leur comportement changent.

La documentation est régie par le même système de gestion de sources que le code.
Elle se trouve dans le répertoire `django/trunk/docs`_ de notre dépôt Subversion.
Chaque document en ligne est un fichier texte séparé dans le dépôt.

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

Où l'obtenir
============

Vous pouvez consulter la documentation de Django de plusieurs manières. Les voici
dans leur ordre de préférence:

Sur le Web
----------

La version la plus récente de la documentation de Django est disponible à
l'adresse http://docs.djangoproject.com/en/dev/. Ces pages HTML sont générées
automatiquement à partir des fichiers texte dans le système de contrôle de
version. Elles reflètent donc "le plus récent et le meilleur" de Django -- elles
contiennent les dernières corrections et ajouts, et traitent des dernières
fonctionnalités de Django qui pourraient n'être disponibles qu'aux utilisateurs
de la version de développement de Django. (Lire "les différences entre les
versions" ci-dessous.)

Nous vous encourageons à participer à l'amélioration de la documentation en
soumettant vos modifications, corrections et suggestions dans le
`système de tickets`_. Les développeurs de Django consultent ce système très
activement et se servent de vos retours afin d'améliorer la documentation pour
tous.

Veuillez toutefois noter que les tickets doivent explicitement traiter de
documentation, au lieu de contenir des questions. Si vous avez besoin d'aide par
rapport à votre propre installation de Django, essayez plutôt la
`mailing list django-users`_ ou le `canal IRC #django`_.

.. _système de tickets: http://code.djangoproject.com/simpleticket?component=Documentation
.. _mailing list django-users: http://groups.google.com/group/django-users
.. _canal IRC #django: irc://irc.freenode.net/django

En mode texte
-------------

Pour une consultation une fois déconnecté, ou pour des raisons pratiques, vous
pouvez consulter la documentation de Django en mode texte.

Si vous utilisez une version officielle de Django, notez que le répertoire
compressé (tarball) du code inclut un répertoire ``docs/``, qui contient toute
la documentation relative à cette version.

Si vous utilisez la version de développement de Django (couramment nommé le
"trunk" de Subversion, ou Subversion "trunk"), notez que le répertoire ``docs/``
contient toute la documentation. Vous pouvez le mettre jour via ``svn up``
exactement comme vous mettez à jour le code Python, afin d'en obtenir les
dernières modifications.

Vous pouvez obtenir la dernière version de la documentation de Django à partir
de Subversion en utilisant cette commande shell:

.. code-block:: bash

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

Un moyen de tirer profit de la documentation en mode texte est l'utilisation
de l'utilitaire Unix ``grep`` qui permet la recherche d'une phrase dans toute
la documentation. Par exemple, ceci vous montrera chaque occurrence de la phrase
"max_length" dans n'importe quel document Django:

.. code-block:: bash

    $ grep -r max_length /chemin/vers/django/docs/

En HTML, localement
-------------------

Vous pouvez obtenir une copie locale de la documentation HTML en suivant ces
étapes:

    * La documentation de Django utilise un système appelé Sphinx__ pour
      convertir les fichiers texte en HTML. Vous devrez installer Sphinx en
      téléchargeant et en installant le paquet à partir du site web de Sphinx,
      ou via ``easy_install`` de Python:
      
      .. code-block:: bash

            $ easy_install Sphinx

    * Utilisez ensuite le ``Makefile`` inclus pour convertir la documentation en
      HTML:

      .. code-block:: bash

            $ cd chemin/vers/django/docs
            $ make html

      Pour cela, vous aurez besoin que `GNU Make`__ soit installé.

    * La documentation HTML sera située dans ``docs/_build/html``.

.. note::

    La génération de la documentation de Django fonctionnera avec les
    versions de Sphinx 0.6 ou ultérieures, cependant, nous vous recommandons
    l'utilisation de la version 1.0.2 ou ultérieure.

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

Différences entre les versions
==============================

Comme nous l'avons dit plus haut, la documentation texte dans le dépôt Subversion
contient "le plus récent et le meilleur" des modifications et ajouts. Ces
modifications portent souvent sur la documentation de nouvelles fonctionnalités
ajoutées à la version de développement de Django -- la version Subversion
("trunk") de Django. Cela mérite de vous expliquer notre politique de
maintenance pour la documentation des différentes versions du framework.

Nous suivons cette politique:

    * La documentation sur djangoproject.com est une version HTML de la plus
      récente documentation issue de Subversion. Cette documentation correspond
      à la dernière version officielle de Django, plus les éventuels ajouts et
      modifications de fonctionnalités *depuis* cette dernière version.

    * Lorsque nous ajoutons des fonctionnalités à la version de développement de
      Django, nous essayons de mettre à jour la documentation lors du même
      commit Subversion.

    * Afin de distinguer les modifications/ajouts dans la documentation, nous
      utilisons la phrase "Nouveau dans la version X.Y", X.Y étant la prochaine
      version officielle (donc la version actuellement développée)

    * La documentation pour une version particulière de Django est figée dès
      lors que la version paraît officiellement. Celle-ci constitue donc un
      instantané de la documentation au moment de la parution de la version.
      Nous ferons des exceptions dans le cas de mises à jour rétroactives liées
      par exemple à la sécurité. Une fois la documentation figée, nous ajoutons
      une note au début de chaque document figé disant "Cette documentation est
      figée à la version XXX de Django" et mettons des liens vers la version
      actuelle du document.

    * La `page web principale de la documentation`_ inclut des liens vers la
      documentation de toutes les versions précédentes.

.. _page web principale de la documentation: http://docs.djangoproject.com/en/dev/