Le guide de style du guide

Comme avec toute documentation, avoir un format consistant aide à rendre le document plus compréhensible. Afin de rendre ce guide plus facile à assimiler, toutes les contributions doivent se tenir aux règles de ce guide de style, le cas échéant.

Le guide est écrit avec du reStructuredText.

Note

Des parties du guide peuvent ne pas respecter encore le guide de style. N’hésitez pas à mettre à jour ces parties pour les mettre en conformité avec le guide de style du guide.

Note

Sur n’importe quelle page du HTML rendu, vous pouvez cliquer “Afficher le code source de la page” pour voir comment les auteurs ont stylé la page.

Pertinence

Efforcez-vous de garder toutes les contributions relatives aux but du guide.

  • Évitez d’inclure trop d’information sur des sujets qui ne sont pas directement liés au développement Python.

  • Préférez faire un lien vers d’autres sources si l’information est déjà sortie. Assurez-vous de décrire quoi et pourquoi vous faites un lien.

  • Citez les références quand c’est nécessaire.

  • Si un sujet n’est pas directement pertinent pour Python, mais est utile en conjonction avec Python (c’est à dire Git, GitHub, les bases de données), référencez en faisant un lien vers des ressources utiles, et décrivez pourquoi c’est utile pour Python.

  • En cas de doute, demandez.

Rubriques

Utilisez les styles suivants pour les rubriques.

Titre du chapitre:

#########
Chapter 1
#########

Titre de page:

===================
Time is an Illusion
===================

Rubriques de la section:

Lunchtime Doubly So
-------------------

Rubriques de la sous-section:

Very Deep
~~~~~~~~~

Prose

Faites des retours à la ligne à 78 caractères. Quand c’est nécessaire, les lignes peuvent dépasser 78 caractères, particulièrement si faire des retours à la ligne rend le texte source plus difficile à lire.

Utilisez la virgule de série (aussi connue comme la virgule d’Oxford) est 100% non-optionnel. Toute tentative pour soumettre un contenu avec une virgule manquante donnera lieu à un bannissement permanent de ce projet, pour cause d’absence complète et totale de goût.

Bannissement? C’est une blague? Nous espérons ne jamais avoir à le découvrir.

Exemples de code

Faites des retours à la ligne à 70 caractères pour tous les exemples de code, pour éviter des barres de défilement horizontales.

Exemples de ligne de commande:

.. code-block:: console

    $ run command --help
    $ ls ..

Assurez-vous d’inclure le préfixe $ avant chaque ligne.

Exemples d’interpréteur Python:

Label the example::

.. code-block:: python

    >>> import this

Exemples d’interpréteur Python:

Descriptive title::

.. code-block:: python

    def get_answer():
        return 42

Liens externes

  • Préférez des étiquettes pour les sujets biens connus (ex: des noms complets) quand vous faites des liens:

    Sphinx_ is used to document Python.

.. _Sphinx: http://sphinx.pocoo.org

  • Préférez utiliser des étiquettes descriptives pour les liens “inline” plutôt que de laisser des liens en brut:

    Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_

  • Evitez d’utiliser des étiquettes comme “cliquez ici”, “ceci”, etc. Préférez des étiquettes descriptives (notamment pour le référencement) à la place.

Liens vers des sections dans le guide

Pour faire des références croisées à d’autres parties de cette documentation, utilisez mot-clé et étiquettes :ref:.

Pour faire référence aux étiquettes plus claires et uniques, ajoutez toujours un suffixe``-ref``:

.. _some-section-ref:

Some Section
------------

Notes et alertes

Utilisez les directives d’admonitions appropriées quand vous ajoutez des notes.

Notes:

.. note::
    The Hitchhiker’s Guide to the Galaxy has a few things to say
    on the subject of towels. A towel, it says, is about the most
    massively useful thing an interstellar hitch hiker can have.

Alertes:

.. warning:: DON'T PANIC

TODOs

Merci de marquer tous les endroits incomplets du guide avec une directive todo. Pour éviter d’encombrer la Liste de choses à faire (“Todo”), utilisez un seul todo pour les bouts de code ou les sections incomplètes importantes.

.. todo::
    Learn the Ultimate Answer to the Ultimate Question
    of Life, The Universe, and Everything