Documentation¶

Nouvelle Traduction d’une Langue¶

Nous souhaitons créer des traductions aussi complètes que possible. Cependant, il peut arriver des fois où un fichier de traduction n’est pas à jour. Vous devriez toujours considérer la version anglais comme la version qui fait autorité.

Si votre langue n’est pas dans les langues actuellement proposées, merci de nous contacter sur Github et nous envisagerons de créer un squelette de dossier pour cette langue. Les sections suivantes sont les premières par lesquelles vous devriez commencer puisque ce sont des fichiers qui ne changent pas souvent:

• index.rst

• intro.rst

• quickstart.rst

• installation.rst

• dossier /intro

• dossier /tutorials-and-examples

Note pour les Administrateurs de la Doc¶

La structure de tous les dossiers de langue doivent refléter la structure du dossier anglais. Si la structure change pour la version anglaise, nous devrions appliquer ces changements dans les autres langues.

Par exemple, si un nouveau fichier anglais est créé dans en/file.rst, nous devrions:

• Ajouter le fichier dans les autres langues : fr/file.rst, zh/file.rst, …

• Supprimer le contenu, mais en gardant les title, informations meta et d’éventuels éléments toc-tree. La note suivante sera ajoutée en anglais tant que personne n’a transmis le fichier:

  File Title
  ##########
  
  .. note::
      The documentation is not currently supported in XX language for this
      page.
  
      Please feel free to send us a pull request on
      `Github <https://github.com/cakephp/docs>`_ or use the **Improve This Doc**
      button to directly propose your changes.
  
      You can refer to the English version in the select top menu to have
      information about this page's topic.
  
  // If toc-tree elements are in the English version
  .. toctree::
      :maxdepth: 1
  
      one-toc-file
      other-toc-file
  
  .. meta::
      :title lang=xx: File Title
      :keywords lang=xx: title, description,...
  

Astuces de traducteurs¶

• Parcourez et modifiez le contenu à traduire dans le langage voulu - sinon vous ne verrez pas ce qui a déjà été traduit.

• N’hésitez pas à plonger droit dans votre langue qui existe déjà dans le livre.

• Utilisez une Forme Informelle.

• Traduisez à la fois le contenu et le titre en même temps.

• Comparez au contenu anglais avant de soumettre une correction (si vous corrigez quelque chose, mais n’intégrez pas un changement “en amont”, votre soumission ne sera pas acceptée).

• Si vous avez besoin d’écrire un terme anglais, entourez le avec les balises <em>. Ex: « asdf asdf Controller asdf » ou « asdf asdf Kontroller (Controller) asfd » comme il se doit.

• Ne soumettez pas de traductions partielles.

• Ne modifiez pas une section avec un changement en attente.

• N’utilisez pas d” entités HTML pour les caractères accentués, le livre utilise UTF-8.

• Ne changez pas les balises (HTML) de façon significative ou n’ajoutez pas de nouveau contenu.

• Si le contenu original manque d’informations, soumettez une modification pour cette version originale.

Longueur des lignes¶

Les lignes de texte doivent être de 80 colonnes au maximum. Seules exceptions, pour les URLs longues et les extraits de code.

En-têtes et Sections¶

Les sections d’en-tête sont créées par le soulignage du titre avec les caractères de ponctuation, avec une longueur de texte au moins aussi longue.

• # Est utilisé pour indiquer les titres de page.

• = Est utilisé pour les sections dans une page.

• - Est utilisé pour les sous-sections.

• ~ Est utilisé pour les sous-sous-sections.

• ^ Est utilisé pour les sous-sous-sous-sections.

Les en-têtes ne doivent pas être imbriqués sur plus de 5 niveaux de profondeur. Les en-têtes doivent être précédés et suivis par une ligne vide.

Les Paragraphes¶

Les paragraphes sont simplement des blocks de texte, avec toutes les lignes au même niveau d’indentation. Les paragraphes ne doivent être séparés par plus d’une ligne vide.

Le balisage interne¶

• Un astérisque: text pour une accentuation (italiques) Nous les utiliserons pour mettre en exergue des infos générales.

  • *text*.

• Deux astérisques: text pour une forte accentuation (caractères gras) Nous les utiliserons pour les répertoires de travail, les sujets de liste à puce, les noms de table et en excluant le mot « table » suivant.

  • **/config/Migrations**, **articles**, etc.

• Deux backquotes: text pour les exemples de code Nous les utiliserons pour les noms d’options de méthode, les noms de colonne des tables, les noms d’objet en excluant le mot « object » suivant et pour les noms de méthode/fonction – en incluant « () ».

  • ``cascadeCallbacks``, ``true``, ``id``, ``PagesController``, ``config()``, etc.

Si les astérisques ou les backquotes apparaissent dans le texte et peuvent être confondus avec les délimiteurs du balisage interne, ils doivent être échappés avec un backslash.

Le balisage interne a quelques restrictions:

• Il ne doit pas être imbriqué.

• Le contenu ne doit pas commencer ou finir avec un espace: * text* est mauvais.

• Le contenu doit être séparé du texte environnant par des caractères qui ne sont pas des mots. Utilisez un backslash pour échapper pour régler le problème: unmot\ *engras*\ long.

Listes¶

La liste du balisage est très similaire à celle de markdown. Les listes non ordonnées commencent par une ligne avec un unique astérisque et un espace. Les listes numérotées peuvent être créées avec, soit les numéros, soit # pour une numérotation automatique:

* C'est une balle
* Ici aussi. Mais cette ligne
  a deux lignes.

1. Première ligne
2. Deuxième ligne

#. Numérotation automatique
#. Va vous faire économiser du temps.

Les listes indentées peuvent aussi être créées, en indentant les sections et en les séparant avec une ligne vide:

* Première ligne
* Deuxième ligne

    * Allez plus profondément
    * Whoah

* Retour au premier niveau.

Les listes avec définitions peuvent être créées en faisant ce qui suit:

term
    définition
CakePHP
    Un framework MVC pour PHP

Les termes ne peuvent pas être sur plus d’une ligne, mais les définitions peuvent être multi-lignes et toutes les lignes doivent toujours être indentées.

Liens¶

Il y a plusieurs types de liens, chacun avec ses propres utilisations.

`Lien externe vers php.net <https://php.net>`_

Description des classes et de leur contenu¶

La documentation de CakePHP utilise phpdomain pour fournir des directives sur mesure pour décrire les objets PHP et les constructs. Utiliser les directives et les modèles est requis pour donner une bonne indexation et des fonctionnalités de référencement croisé.

Description des classes et constructs¶

Chaque directive remplit l’index, et l’index des espaces de nom.

.. php:global:: name¶

Cette directive déclare une nouvelle variable globale PHP.

.. php:function:: name(signature)¶

Définit une nouvelle fonction globale en-dehors de la classe.

.. php:const:: name¶

Cette directive déclare une nouvelle constante PHP, vous pouvez aussi l’utiliser imbriquée à l’intérieur d’une directive de classe pour créer les constantes de classe.

.. php:exception:: name¶

Cette directive déclare un nouvelle Exception dans l’espace de noms courant. La signature peut inclure des arguments du constructeur.

.. php:class:: name¶

Décrit une classe. Méthodes, attributs, et constantes appartenant à la classe doivent être à l’intérieur du corps de la directive:

.. php:class:: MyClass

    Description de la Classe

   .. php:method:: method($argument)

   Description de la méthode

Attributs, méthodes et constantes ne doivent pas être imbriqués. Ils peuvent aussi suivre la déclaration de classe:

.. php:class:: MyClass

    Texte sur la classe

.. php:method:: methodName()

    Texte sur la méthode

Voir aussi

php:method, php:attr, php:const

.. php:method:: name(signature)¶

Décrit une méthode de classe, ses arguments, les valeurs retournées et les exceptions:

.. php:method:: instanceMethod($one, $two)

    :param string $un: Le premier param\ètre.
    :param string $deux: Le deuxième param\ètre.
    :returns: Un tableau de trucs.
    :throws: InvalidArgumentException

   C\'est un m\éthode d\'instanciation.

.. php:staticmethod:: ClassName::methodName(signature)¶

Décrire une méthode statique, ses arguments, les valeurs retournées et les exceptions.

see php:method pour les options.

.. php:attr:: name¶

Décrit une propriété/attribut sur une classe.

.. php:function:: debug(mixed $var, boolean $showHtml = null, $showFrom = true)
    :noindex:

Code source¶

Les blocks de code littéral sont créés en finissant un paragraphe avec ::. Le block littéral doit être indenté, et comme pour tous les paragraphes, être séparé par des lignes uniques:

C'est un paragraphe::

    while ($i--) {
        faireDesTrucs()
    }

C'est un texte régulier de nouveau.

Le texte littéral n’est pas modifié ou formaté, la sauvegarde du niveau d’indentation est supprimée.

Notes et avertissements¶

Il y a souvent des fois où vous voulez informer le lecteur d’une astuce importante, une note spéciale ou un danger potentiel. Les avertissements dans sphinx sont justement utilisés pour cela. Il y a cinq types d’avertissements.

• .. tip:: Les astuces sont utilisées pour documenter ou ré-itérer des informations intéressantes ou importantes. Le contenu de cette directive doit être écrit dans des phrases complètes et inclure toutes les ponctuations appropriées.

• .. note:: Les notes sont utilisées pour documenter une information particulièrement importante. Le contenu de cette directive doit être écrit dans des phrases complètes et inclure toutes les ponctuations appropriées.

• .. warning:: Les avertissements sont utilisés pour documenter des blocks potentiellement dangereux, ou des informations relatives à la sécurité. Le contenu de la directive doit être écrite en phrases complètes et inclure toute la ponctuation appropriée.

• .. versionadded:: X.Y.Z Les avertissements « ajouté en version X.Y.Z » sont utilisés pour spécifier l’ajout de fonctionnalités dans une version spécifique, X.Y.Z étant la version à laquelle l’ajout de la fonctionnalité en question a eu lieu

• .. deprecated:: X.Y.Z À la différence des avertissements « ajouté en version », les avertissements « déprécié en version » servent à indiquer la dépréciation d’une fonctionnalité à une version précise, X.Y.Z étant la version à laquelle le retrait de la fonctionnalité en question a eu lieu.

Tous les avertissements sont faits de la même façon:

.. note::

    Indenté, précédé et suivi par une ligne vide. Exactement comme
    un paragraphe.

Ce texte n'est pas une partie de la note.