Nous attribuons une grande importance à la cohérence et à la lisibilité de la documentation. Après tout, Django a été créé dans un environnement journalistique ! Nous traitons donc la documentation sur un pied d’égalité avec le code : nous visons à l’améliorer aussi souvent que possible.
\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.
Si vous souhaitez commencer à contribuer à la documentation, obtenez la version de développement de Django à partir du dépôt de code source (voir Installation de la version de développement). La version de développement possède la version la plus à jour de la documentation, comme pour le code. Nous reportons aussi les corrections et améliorations de documentation vers la dernière version publiée en fonction de ce que le commiteur décide. Ceci parce qu’il est très avantageux de posséder une documentation de la dernière version publiée la plus à jour et correcte possible (voir Diffé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
$ pip install Sphinx\nWindows
...\\> 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à.
\nLes guides de référence contiennent des références techniques pour les API. Ils présentent le fonctionnement de la machinerie interne de Django avec des instructions d’utilisation.
\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.
\nLors d’utilisation de pronoms en référence à une personne hypothétique, comme dans « a user with a session cookie », il est préférable d’utiliser des pronoms neutres. Au lieu de :
\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.
Voici 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.
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 »).
Web, World Wide Web, the Web – notez que Web commence toujours par une majuscule lorsqu’on fait référence au World Wide Web.
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.
These guidelines regulate the format of our reST (reStructuredText)\ndocumentation:
\nIn section titles, capitalize only initial words and proper nouns.
Wrap the documentation at 80 characters wide, unless a code example\nis significantly less readable when split over two lines, or for another\ngood reason.
The main thing to keep in mind as you write and edit docs is that the\nmore semantic markup you can add the better. So:
\nAdd ``django.contrib.auth`` to your ``INSTALLED_APPS``...\nIsn’t nearly as helpful as:
\nAdd :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...\nThis is because Sphinx will generate proper links for the latter, which\ngreatly helps readers.
\nYou can prefix the target with a ~ (that’s a tilde) to get just the\n« last bit » of that path. So :mod:`~django.contrib.auth` will just\ndisplay a link with the title « auth ».
Use intersphinx to reference Python’s and Sphinx”\ndocumentation.
Add .. code-block:: <lang> to literal blocks so that they get\nhighlighted. Prefer relying on automatic highlighting simply using ::\n(two colons). This has the benefit that if the code contains some invalid\nsyntax, it won’t be highlighted. Adding .. code-block:: python, for\nexample, will force highlighting despite invalid syntax.
Use these heading styles:
\n===\nOne\n===\n\nTwo\n===\n\nThree\n-----\n\nFour\n~~~~\n\nFive\n^^^^\nBesides Sphinx’s built-in markup, Django’s docs\ndefine some extra description units:
\nSettings:
\n.. setting:: INSTALLED_APPS\nTo link to a setting, use :setting:`INSTALLED_APPS`.
Template tags:
\n.. templatetag:: regroup\nTo link, use :ttag:`regroup`.
Template filters:
\n.. templatefilter:: linebreaksbr\nTo link, use :tfilter:`linebreaksbr`.
Field lookups (i.e. Foo.objects.filter(bar__exact=whatever)):
.. fieldlookup:: exact\nTo link, use :lookup:`exact`.
Commandes django-admin:
.. django-admin:: migrate\nTo link, use :djadmin:`migrate`.
Options de ligne de commande django-admin:
.. django-admin-option:: --traceback\nTo link, use :option:`command_name --traceback` (or omit command_name\nfor the options shared by all commands like --verbosity).
Links to Trac tickets (typically reserved for patch release notes):
\n:ticket:`12345`\nDjango’s documentation uses a custom console directive for documenting\ncommand-line examples involving django-admin.py, manage.py, python,\netc.). In the HTML documentation, it renders a two-tab UI, with one tab showing\na Unix-style command prompt and a second tab showing a Windows prompt.
For example, you can replace this fragment:
\nuse this command:\n\n.. code-block:: console\n\n $ python manage.py shell\nwith this one:
\nuse this command:\n\n.. console::\n\n $ python manage.py shell\nNotice two things:
\nYou usually will replace occurrences of the .. code-block:: console\ndirective.
You don’t need to change the actual content of the code example. You still\nwrite it assuming a Unix-y environment (i.e. a '$' prompt symbol,\n'/' as filesystem path components separator, etc.)
The example above will render a code example block with two tabs. The first\none will show:
\n$ python manage.py shell\n(No changes from what .. code-block:: console would have rendered).
The second one will show:
\n...\\> py manage.py shell\nOur policy for new features is:
\n\n\nAll documentation of new features should be written in a way that\nclearly designates the features are only available in the Django\ndevelopment version. Assume documentation readers are using the latest\nrelease, not the development version.
\n
Our preferred way for marking new features is by prefacing the features”\ndocumentation with: « .. versionadded:: X.Y », followed by a mandatory\nblank line and an optional description (indented).
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.
These versionadded and versionchanged blocks should be « self-contained. »\nIn other words, since we only keep these annotations around for two releases,\nit’s nice to be able to remove the annotation and its contents without having\nto reflow, reindent, or edit the surrounding text. For example, instead of\nputting the entire description of a new or changed feature in a block, do\nsomething like this:
.. 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.\nPut the changed annotation notes at the bottom of a section, not the top.
\nAlso, avoid referring to a specific version of Django outside a\nversionadded or versionchanged block. Even inside a block, it’s often\nredundant to do so as these annotations render as « New in Django A.B: » and\n« Changed in Django A.B », respectively.
If a function, attribute, etc. is added, it’s also okay to use a\nversionadded annotation like this:
.. attribute:: Author.middle_name\n\n .. versionadded:: A.B\n\n An author's middle name.\nWe can simply remove the .. versionadded:: A.B annotation without any\nindentation changes when the time comes.
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.
Next, notice how the settings are annotated:
\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.\nThis marks up the following header as the « canonical » target for the\nsetting ADMINS. This means any time I talk about ADMINS,\nI can reference it using :setting:`ADMINS`.
C’est grosso modo ainsi que le tout fonctionne.
\nAvant de valider votre documentation, il est recommandé de lancer le correcteur orthographique. Il est nécessaire d’installer quelques paquets au préalable :
\nPuis, à 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).
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.