We place high importance on the consistency and readability of documentation.\nAfter all, Django was created in a journalism environment! So we treat our\ndocumentation like we treat our code: we aim to improve it as often as\npossible.
\nLes modifications de documentation se présentent généralement sous deux formes :
\nDes améliorations générales : corrections d’orthographe, résolutions d’erreurs et meilleures explications par une écriture plus claire et davantage d’exemples.
Nouvelles fonctionnalités : documentation de fonctionnalités ajoutées au cadre logiciel depuis la version précédente.
Cette section explique comment les rédacteurs peuvent préparer les modifications de documentation de la manière la plus utile possible et qui évite au maximum les erreurs.
\nBien que la documentation de Django soit destinée à être lue au format HTML sur https://docs.djangoproject.com/, nous l’éditons dans un ensemble de fichiers textes pour une souplesse maximale. Ces fichiers se trouvent dans le répertoire de premier niveau docs/ d’une publication de Django.
If you’d like to start contributing to our docs, get the development version of\nDjango from the source code repository\n(see Installation de la version de développement). The development version has the\nlatest-and-greatest documentation, just as it has the latest-and-greatest code.\nWe also backport documentation fixes and improvements, at the discretion of the\nmerger, to the last release branch. That’s because it’s highly advantageous to\nhave the docs for the last release be up-to-date and correct (see\nDifférences entre versions).
\nLa documentation de Django utilise le système de documentation Sphinx, qui se base lui-même sur docutils. L’idée de base est de transformer de la documentation en texte brut avec une mise en forme minimale en HTML, PDF ou tout autre format de sortie.
\nPour construire la documentation localement, installez Sphinx :
\nLinux / macOS
$ python -m pip install Sphinx\nWindows
...\\> py -m pip install Sphinx\nPuis, à partir du répertoire docs, construisez la version HTML :
Linux / macOS
$ make html\nWindows
...\\> make.bat html\nPour commencer à contribuer, il est recommandé de lire la référence reStructuredText.
\nLa documentation construite localement possède un thème graphique différent de celui de la documentation sur docs.djangoproject.com. Cela ne pose pas de problème. Si vos modifications apparaissent correctement sur votre machine locale, elles seront aussi correctes sur le site Web.
\nLa documentation est scindée en plusieurs catégories :
\nLes tutoriels prennent l’utilisateur par la main à travers une série d’étapes pour créer quelque chose.
\nL’aspect important d’un tutoriel est d’aider le lecteur à accomplir quelque chose d’utile, de préférence aussi vite que possible, dans le but de lui donner confiance.
\nExpliquez la nature du problème à résoudre afin que le lecteur comprenne ce que l’on est en train de faire. Ne pensez pas qu’il faille commencer par des explications sur le fonctionnement des choses ; ce qui compte est ce que le lecteur fait, et non pas ce que vous expliquez. Il peut être utile de faire référence à ce que l’on a fait dans des explications a posteriori.
\nLes guides thématiques visent à expliquer un concept ou un sujet d’un point de vue assez général.
\nFaites des liens vers le matériel de référence plutôt que de le répéter. Utilisez des exemples et n’hésitez pas à expliquer des choses qui vous semblent évidentes, il pourrait s’agir de l’explication dont quelqu’un a vraiment besoin.
\nLa mise à disposition de contexte sous-jacent aide les débutants à faire des liens entre le sujet et des éléments qu’ils connaissent déjà.
\nReference guides contain technical references for APIs.\nThey describe the functioning of Django’s internal machinery and instruct in\nits use.
\nRestez bien centré sur le sujet du matériel de référence. Vous pouvez compter sur la connaissance des concepts de base par le lecteur, mais celui-ci cherche à savoir ou à se rappeler comment Django les applique.
\nLes guides de référence ne sont pas l’endroit pour des explications générales. Si vous êtes en train d’expliquer des concepts de base, il pourrait être nécessaire de déplacer ce contenu vers un guide thématique.
\nLes guides pratiques sont des marches à suivre qui accompagnent le lecteur dans une suite d’étapes dans des sujets clés.
\nCe qui compte le plus dans un guide pratique est le résultat attendu par son lecteur. Un guide pratique doit toujours être orienté sur le résultat plutôt que sur des détails internes sur la manière dont Django implémente ce qui est en cours d’étude.
\nCes guides vont plus loin que les tutoriels et comptent sur un certaine connaissance du fonctionnement de Django. On part du principe que le lecteur a suivi les tutoriels. N’hésitez pas à réorienter le lecteur sur un tutoriel adéquat plutôt que de répéter un contenu existant.
\nWhen using pronouns in reference to a hypothetical person, such as « a user with\na session cookie », gender-neutral pronouns (they/their/them) should be used.\nInstead of:
\nhe ou she… utilisez they.
him ou her… utilisez them.
his ou her… utilisez their.
his ou hers… utilisez theirs.
himself ou herself… utilisez themselves.
Essayez d’éviter des mots qui minimisent la difficulté impliquée par une tâche ou une opération, tels que « easily », « simply », « just », « merely », « straightforward », etc. L’expérience des gens ne correspond pas forcément à votre attente, et ceux-ci pourraient ressentir de la frustration lorsqu’ils ne trouvent pas qu’une étape est si simple ou évidente que le texte ne le laissait penser.
\nVoici quelques lignes directrices de style pour des termes fréquemment utilisés dans la documentation :
\nDjango – lorsque vous vous référez au cadriciel, toujours avec un D majuscule. Il n’est en minuscules que dans le code Python et dans le logo djangoproject.com.
email – sans trait d’union.
HTTP – la prononciation anglaise habituelle est « Éitch Ti Ti Pi », le terme doit donc être précédé de « an », et pas « a ».
MySQL, PostgreSQL, SQLite
SQL – lorsqu’on se réfère à SQL, la prononciation attendue est « èsquiouèl » et non pas « sicouèl ». Ainsi, dans une phrase comme « Returns an SQL expression », « SQL » doit être précédé d’un « an » et non pas de « a ».
Python – mettre une majuscule quand c’est une référence au langage.
realize, customize, initialize, etc. – utiliser le suffixe américain « ize » et non « ise ».
subclass – en un mot sans trait d’union, que ce soit pour un verbe (« subclass that model ») ou un nom (« create a subclass »).
the web, web framework – sans majuscule.
website – en un seul mot, sans majuscule.
model – sans majuscule.
template – sans majuscule.
URLconf – trois premières lettres en majuscules, sans espace avant « conf ».
view – sans majuscule.
Ces lignes directrices régulent le format de notre documentation reST (reStructuredText) :
\nDans les titres de section, ne mettez en majuscules que les mots initiaux et les noms propres.
Limitez les lignes de la documentation à 80 caractères, sauf si un exemple de code est manifestement moins lisible lorsqu’il est réparti sur deux lignes, ou pour une autre bonne raison.
La chose principale à garder en tête lors de l’écriture et de l’édition de la documentation est que plus il y a de balisage sémantique, mieux c’est. Donc
\nAdd ``django.contrib.auth`` to your ``INSTALLED_APPS``...\nN’est pas aussi utile que
\nAdd :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...\nLa raison en est que Sphinx va générer des liens adéquats avec ce deuxième exemple, ce qui aide grandement les lecteurs.
\nIl est possible de préfixer la cible par un ~ (caractère tilde) pour que seul le dernier composant du chemin soit affiché. Par exemple, :mod:`~django.contrib.auth` affichera un lien sur le mot « auth » seul.
Utilisez intersphinx pour ajouter des références aux documentations de Python et de Sphinx.
Ajoutez .. code-block:: <lang> aux blocs littéraux pour que leur syntaxe soit mise en évidence. Mais on préfère en général laisser agir la coloration syntaxique automatique en utilisant :: (deux fois deux-points). L’avantage est que du code contenant de la syntaxe non valable ne sera pas coloré. Si par exemple on ajoute .. code-block:: python, la coloration syntaxique sera forcée même si la syntaxe n’est pas entièrement valable.
Pour améliorer la lisibilité, utilisez .. admonition:: Titre descriptif plutôt que .. note::. Utilisez ces boîtes de manière parcimonieuse.
Utilisez ces styles d’en-têtes
\n===\nOne\n===\n\nTwo\n===\n\nThree\n-----\n\nFour\n~~~~\n\nFive\n^^^^\nUtilisez :rfc: pour faire référence à des RFC et essayez de faire le lien vers la section adéquate si possible. Par exemple, écrivez :rfc:`2324#section-2.3.2` ou :rfc:`Texte de lien personnalisé <2324#section-2.3.2>`.
Utilisez :pep: pour faire référence aux propositions d’amélioration de Python (PEP) et essayez de faire le lien vers la section adéquate si possible. Par exemple, écrivez :pep:`20#easter-egg` ou :pep:`Easter Egg <20#easter-egg>`.
Utilisez :mimetype: pour vous référer à un type MIME sauf si la valeur est entre guillemets pour un exemple de code.
Utilisez :envvar: pour vous référer à une variable d’environnement. Il est parfois aussi nécessaire de définir une référence à la documentation pour cette variable d’environnement en utilisant .. envvar::.
En plus du balisage propre à Sphinx, la documentation de Django définit quelques unités descriptives supplémentaires :
\nRéglages
\n.. setting:: INSTALLED_APPS\nPour faire un lien vers un réglage, utilisez :setting:`INSTALLED_APPS`.
Balises de gabarit
\n.. templatetag:: regroup\nPour faire le lien, utilisez :ttag:`regroup`.
Filtres de gabarit
\n.. templatefilter:: linebreaksbr\nPour faire le lien, utilisez :tfilter:`linebreaksbr`.
Requêtes de champs (par ex. Foo.objects.filter(bar__exact=qqchose)):
.. fieldlookup:: exact\nPour faire le lien, utilisez :lookup:`exact`.
Commandes django-admin:
.. django-admin:: migrate\nPour faire le lien, utilisez :djadmin:`migrate`.
Options de ligne de commande django-admin:
.. django-admin-option:: --traceback\nPour faire le lien, utilisez :option:`nom_commande --traceback` (ou omettez nom_commande pour les options partagées par toutes les commandes comme --verbosity).
Liens vers les tickets Trac (typiquement réservés pour les notes de publication des versions correctives)
\n:ticket:`12345`\nLa documentation de Django utilise une directive console personnalisée pour la documentation des exemples en ligne de commande impliquant django-admin, manage.py, python, etc.). Dans la production HTML de la documentation, deux onglets apparaîtront dans l’interface, un avec l’invite de commande de type Unix et l’autre avec une invite de commande de style Windows.
Par exemple, vous pouvez remplacer ce fragment
\nuse this command:\n\n.. code-block:: console\n\n $ python manage.py shell\npar celui-ci
\nuse this command:\n\n.. console::\n\n $ python manage.py shell\nRemarquez deux choses :
\nVous allez généralement remplacer les occurrences de la directive .. code-block:: console.
Vous n’avez pas besoin de modifier le contenu effectif de l’exemple de code. Vous l’écrivez toujours en imaginant un environnement de type Unix (c’est-à-dire un symbole d’invite '$', '/' comme séparateur de chemins de systèmes de fichiers, etc.)
L’exemple ci-dessus va produire un bloc d’exemple de code avec deux onglets. Le premier contiendra :
\n$ python manage.py shell\n(aucun changement par rapport au rendu .. code-block:: console standard).
Le second contiendra :
\n...\\> py manage.py shell\nNotre politique pour les nouvelles fonctionnalités est la suivante :
\n\n\nAll documentation of new features should be written in a way that\nclearly designates the features that are only available in the Django\ndevelopment version. Assume documentation readers are using the latest\nrelease, not the development version.
\n
La méthode préférée pour marquer les nouvelles fonctionnalités est de précéder leur documentation par « .. versionadded:: X.Y », suivi d’une ligne vierge obligatoire et d’une description facultative (avec indentation).
General improvements or other changes to the APIs that should be emphasized\nshould use the « .. versionchanged:: X.Y » directive (with the same format\nas the versionadded mentioned above.
Ces blocs versionadded et versionchanged doivent être « autonomes », c’est-à-dire que dans la mesure où ces annotations ne sont conservées que dans deux versions principales, il est utile de pouvoir simplement les enlever sans devoir remettre en forme, changer l’indentation ou modifier le texte avoisinant. Par exemple, au lieu de placer toute la description d’une fonctionnalité nouvelle ou modifiée dans un bloc, faite quelque chose comme ceci
.. class:: Author(first_name, last_name, middle_name=None)\n\n A person who writes books.\n\n ``first_name`` is ...\n\n ...\n\n ``middle_name`` is ...\n\n .. versionchanged:: A.B\n\n The ``middle_name`` argument was added.\nPlacez les annotations pour les modifications au bas de la section, et non pas au-dessus.
\nDe même, évitez de faire référence à une version spécifique de Django en dehors des blocs versionadded et versionchanged. Même dans un bloc, il est souvent redondant de mentionner des versions puisque le rendu automatique de ces annotations produit respectivement « New in Django A.B » et « Changed in Django A.B ».
Si une fonction, un attribut, etc. a été ajouté, il est aussi admis d’utiliser une annotation versionadded comme ceci
.. attribute:: Author.middle_name\n\n .. versionadded:: A.B\n\n An author's middle name.\nNous pouvons enlever l’annotation .. versionadded:: A.B sans aucun changement d’indentation lorsque ce sera le bon moment.
Optimisez la taille de compression des images quand c’est possible, pour les fichiers PBG, utilisez OptiPNG et advpng de AdvanceCOMP :
$ cd docs\n$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`\n$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`\nCet exemple est basé sur la version 0.7.5 de OptiPNG. Les versions plus anciennes peuvent se plaindre que l’option -strip all perd des données.
Pour un exemple rapide sur la manière dont tout s’enchaîne, considérez l’exemple hypothétique suivant :
\nTout d’abord, la disposition générale du document ref/settings.txt pourrait ressembler à ceci :
========\nSettings\n========\n\n...\n\n.. _available-settings:\n\nAvailable settings\n==================\n\n...\n\n.. _deprecated-settings:\n\nDeprecated settings\n===================\n\n...\nEnsuite, le document topics/settings.txt pourrait contenir quelque chose comme :
You can access a :ref:`listing of all available settings\n<available-settings>`. For a list of deprecated settings see\n:ref:`deprecated-settings`.\n\nYou can find both in the :doc:`settings reference document\n</ref/settings>`.\nWe use the Sphinx doc cross-reference element when we want to\nlink to another document as a whole and the ref element when\nwe want to link to an arbitrary location in a document.
Puis, voyez comment les réglages sont annotés :
\n.. setting:: ADMINS\n\nADMINS\n======\n\nDefault: ``[]`` (Empty list)\n\nA list of all the people who get code error notifications. When\n``DEBUG=False`` and a view raises an exception, Django will email these people\nwith the full exception information. Each member of the list should be a tuple\nof (Full name, email address). Example::\n\n [('John', 'john@example.com'), ('Mary', 'mary@example.com')]\n\nNote that Django will email *all* of these people whenever an error happens.\nSee :doc:`/howto/error-reporting` for more information.\nCeci balise l’en-tête suivante comme la cible « canonique » du réglage ADMINS. Cela signifie que lors de chaque mention de ADMINS, on peut y faire référence avec :setting:`ADMINS`.
C’est grosso modo ainsi que le tout fonctionne.
\nAvant de commiter la documentation, il est recommandé de lancer le correcteur orthographique. Vous devez pour cela installer d’abord sphinxcontrib-spelling <https://pypi.org/project/sphinxcontrib-spelling/>. Puis, à partir du répertoire docs, lancez make spelling. Le cas échéant, les mots faux ainsi que le fichier et le numéro de ligne où ils apparaissent seront enregistrés dans _build/spelling/output.txt.
Si vous rencontrez des faux positifs (des erreurs signalées qui n’en sont pas), faites l’une des choses suivantes :
\nEntourez le code imbriqué ou les noms de marques ou de technologie avec des accents graves(`).
Cherchez des synonymes que le correcteur orthographique connaît.
Si vous êtes certain-e que le mot utilisé est correct, ajoutez-le à la liste docs/spelling_wordlist (en prenant soin de respecter l’ordre alphabétique).
Les liens de la documentation peuvent casser ou être modifiés pour ne plus être des liens canoniques. Sphinx fournit un constructeur qui peut vérifier si les liens de la documentation fonctionnent. À partir du répertoire docs, exécutez make linkcheck. Le résultat s’affiche dans le terminal, mais peut aussi être obtenu dans _build/linkcheck/output.txt et _build/linkcheck/output.json.
Les lignes qui ont un statut de « working » sont bonnes, celles qui sont marquées comme « unchecked » ou « ignored » n’ont pas été contrôlées soit car il n’est pas possible de le faire, soit parce qu’elles correspondent à des règles à ignorer dans la configuration.
\nEntries that have a status of « broken » need to be fixed. Those that have a\nstatus of « redirected » may need to be updated to point to the canonical\nlocation, e.g. the scheme has changed http:// → https://. In certain\ncases, we do not want to update a « redirected » link, e.g. a rewrite to always\npoint to the latest or stable version of the documentation, e.g. /en/stable/ →\n/en/3.2/.
Consultez Traduction de la documentation de Django si vous souhaitez aider à traduire la documentation dans une autre langue.
\ndjango-adminLien vers cette rubrique#Sphinx peut générer une page de manuel pour la commande django-admin. Ceci est configuré dans docs/conf.py. Au contraire d’autres productions de documentation, cette page de manuel devrait être contenue dans le dépôt de Django et dans ses publications comme docs/man/django-admin.1. Il n’est pas nécessaire de mettre à jour ce fichier lors de la mise à jour de la documentation, car sa mise est jour fait partie du processus de publication.
Pour générer une version à jour de la page de manuel, lancez make man dans le répertoire docs. La nouvelle page de manuel sera écrite dans docs/_build/man/django-admin.1.