From bd285e01cb8f097a58927b5367d47ce5f0dcf794 Mon Sep 17 00:00:00 2001 From: Antoine <43954001+awecx@users.noreply.github.com> Date: Fri, 22 May 2020 22:02:24 +0200 Subject: [PATCH] Encore des changements sur le README. (#1293) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * make et make serve * Modifications diverses. * Réorganisation des sections. * Modif mineure. * Modif mineures sur une énumération. * Suggestions de christopheNan Co-authored-by: Christophe Nanteuil <35002064+christopheNan@users.noreply.github.com> * Modifs mineures. * Ajout d'une sous-section sur les paramètres de fonction. * Encore quelques améliorations. * Test. * Ajout d'une section « balises ». * Ajout d'un lien dans la section balise. * Correction dans la section balise. * Test. * Dernières modifs. * Ajout URL dans la section « liens hypertextes ». * Modif. URL dans la section « liens hypertextes ». * Apply suggestions from deronnax. Co-authored-by: Mathieu Dupuy * Remarques de deronnax. Co-authored-by: Christophe Nanteuil <35002064+christopheNan@users.noreply.github.com> Co-authored-by: Mathieu Dupuy --- CONTRIBUTING.rst | 222 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 157 insertions(+), 65 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index fc8c4590..1575f9a9 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,19 +1,26 @@ -Guide de contribution à la documention via GitHub. -================================================== +Guide de contribution à la documention via GitHub +================================================= + +Instructions +------------ Prérequis ---------- +~~~~~~~~~ - un compte `Github `_ ; - un client ``git`` `Linux `_ ou `Windows `_ ; - un éditeur de fichier ``.po`` (comme `Poedit `_). -Instructions ------------- +Équipez-vous aussi de quelques outils pour vous aider dans +votre traduction (voir `Outils utiles pour la traduction`_). + + +*fork* personnel +~~~~~~~~~~~~~~~ Pour commencer vous aurez besoin de *forker* le dépôt des sources `python-docs-fr `_ en cliquant sur son bouton -``Fork``. Ceci crée une copie du projet sur votre compte Github : un endroit +``Fork``. Ceci crée une copie du projet sur votre compte Github, c'est un endroit où vous avez le droit de faire des modifications. Étape par étape : @@ -33,10 +40,14 @@ où vous avez le droit de faire des modifications. # ceci permet à *git* de savoir quoi et où est *upstream* git remote add upstream https://github.com/python/python-docs-fr.git + +Réservation d'un fichier +~~~~~~~~~~~~~~~~~~~~~~~~ + Ensuite, vous devez trouver un fichier sur lequel travailler -(pour vous aiguiller, vous pouvez vous rendre à `Que traduire ?`_ et lire -les explications concernant `potodo`_ qui vous permettra de voir ce qui a -déjà été traduit et ce qui ne l'a pas été). +(pour vous aiguiller, lisez la section `Que traduire ?`_). Nous vous conseillons +de choisir, si possible, un fichier traitant d'un sujet que vous maitrisez, cela +vous aidera grandement à produire une traduction de bonne qualité. Une fois que vous avez choisi un fichier sur lequel travailler, veuillez ouvrir un `ticket sur Github `_ @@ -45,9 +56,6 @@ en indiquant dans le titre ``Je travaille sur DOSSIER/FICHIER.po`` Ceci permet à `potodo`_ de détecter via l'API Github les fichiers ``.po`` réservés dans les tickets et les *pull requests*. -Équipez-vous aussi de quelques outils pour vous aider dans -votre traduction (voir `Outils utiles pour la traduction`_). - Vous êtes maintenant prêt. Chaque fois que vous commencerez un nouveau fichier, suivez cette procédure : @@ -82,6 +90,7 @@ Ici, remplacez « library/sys.po » par le fichier que vous avez choisi préc poedit library/sys.po + Ou lancez simplement Poedit puis « Fichier » → « Ouvrir ». Si vous n'utilisez pas Poedit, vous pouvez utiliser `powrap `_ @@ -93,16 +102,39 @@ ou `powrap library/sys.po` (un fichier en particulier) : powrap -m -Pour l'orthographe, une liste blanche de certains termes techniques ou -de noms propres, comme « Guido », « C99 » ou « sérialisable », est -stockée dans le fichier « dict » à la racine du projet. Vous pouvez -bien sûr y ajouter une entrée si nécessaire. -La commande suivante lance les vérifications nécessaires. + +Traduction +~~~~~~~~~~ + +Vous pouvez commencer à présent commencer à traduire le fichier en respectant les `Conventions`_ du projet. + +La commande suivante lance les vérifications nécessaires : .. code-block:: bash make verifs +Une fois la traduction finie, il faut compiler la documentation, c'est-à-dire générer les fichiers HTML +affichés par le site, pour les relire. Si la commande précédente s'est exécutée sans erreur, la +compilation ne devrait pas échouer. + +.. code-block:: bash + + make + +Vérifiez alors le rendu de la traduction « en vrai ». Lancez un serveur de +documentation local : + +.. code-block:: bash + + make serve + +La documentation est publiée l'adresse ``_ +(ou tout autre port indiqué par la sortie de la commande précédente). Vous pouvez +recommencer les étapes de cette section autant de fois que nécessaire. + +*pull request* +~~~~~~~~~~~~~~ C'est le moment de `git add` et `git commit`. `git add` place nos modifications dans l'index de Git en @@ -123,7 +155,7 @@ Puis on propage les modifications dans le dépôt local avec un commit. Poussez ensuite vos modifications sur votre fork Github. Le -u n'est utile qu'une fois pour que votre client git se souvienne que cette branche est liée à votre fork Github (et donc que vos futurs `git pull` et -`git push` sachent quoi tirer) +`git push` sachent quoi tirer). .. code-block:: bash @@ -144,7 +176,7 @@ sur une autre branche) : .. code-block:: bash - git checkout library/sys + git checkout library-sys git pull # pour rapatrier les modifications que vous auriez acceptées # sur l'interface web. @@ -176,10 +208,10 @@ les plus anciennes par l'`équipe de documentation `_. Que traduire ? -~~~~~~~~~~~~~~ +-------------- Vous pouvez utiliser `potodo`_, un outil fait pour trouver des fichiers ``po`` -à traduire. Une fois installé, utilisez la commande ``potodo`` dans votre clone +à traduire. Une fois installé, utilisez la commande ``make todo`` dans votre clone local. Vous pouvez choisir n'importe quel fichier non réservé dans la liste @@ -190,30 +222,83 @@ renvoyée par la commande **à l'exception** des fichiers de : - ``distutils/`` et ``install/`` car ces pages seront bientôt obsolètes. Vous pouvez commencer par des tâches faciles comme réviser les entrées -*fuzzy* pour aider à garder la documentation à jour (trouvez les entrées -*fuzzy* l'aide de `make fuzzy`). +*fuzzy* pour aider à garder la documentation à jour (trouvez-les à l'aide +de `make fuzzy`). Une entrée *fuzzy* correspond à une entrée déjà traduite +mais dont la source en anglais a été remodifiée depuis (correction orthographique, +changement d'un terme, ajout ou suppression d'une phrase…). Elles sont +généralement plus « faciles » à traduire. Vous pouvez également relire des entrées déjà traduites pour vous faire une idée, et passer ensuite à la traduction de celles qui ne le sont pas encore. -Vous pouvez les trouver à l'aide de `make todo`… -Vous pouvez aussi « traduire » des liens hypertextes -(par exemple s'il s'agit d'un lien vers un article de Wikipédia qui possède une -traduction). -Modifiez le lien et sa description dans ce cas. -Si aucune traduction de la cible n'existe, ne traduisez pas le titre. -Dans les fichiers, ne traduisez pas le contenu des balises telles que -``:ref :...`` et ``:term :...``. +Conventions +----------- -Si vous devez absolument utiliser un mot anglais, mettez-le en *italique* -(entouré par des astérisques). +Prototypes et exemples +~~~~~~~~~~~~~~~~~~~~~~ -Pour les caractères spéciaux, référez-vous à la section -`Caractères spéciaux`_. +Il ne faut pas traduire le nom des éléments de la bibliothèque standard (noms +de fonctions, paramètres de ces fonctions, constantes etc.) mais les laisser +tels quel, entourés d'astérisques dans les blocs de texte. +Si la documentation contient des exemples, vous *pouvez* traduire les noms +utilisés, en prenant garde d'être cohérent. Vous pouvez ainsi traduire : -Conseils --------- +.. code-block:: python + + def sample_function(): + result = thread.join(timeout=...) + ... + +en + +.. code-block:: python + + def fonction_exemple(): + resultat = thread.join(timeout=...) + ... + +mais pas en + +.. code-block:: python + + def fonction_exemple(): + resultat = fildexécution.attendre(délai=...) + ... + +Liens hypertextes +~~~~~~~~~~~~~~~~~ + +Il faut transformer les liens hypertextes qui redirigent vers une page dont il +existe une version française (c'est notamment très souvent le cas pour les +articles de Wikipédia). Modifiez le lien *et* sa description dans ce cas. +Si aucune traduction de la cible n'existe, ne traduisez pas la description. +Par exemple, ```Conway's Game of Life `_`` +doit devenir ```Jeu de la vie `_``. + + +Balises +~~~~~~~ + +Ne traduisez pas le contenu des balises comme ``:ref:...`` ou ``:class:...``. +Vous devez cependant traduire les balises ``:term:...``, qui font référence à +un concept ou une primitive Python défini dans le `glossaire `_. +La syntaxe est ``:term:nom_français``. Par exemple, traduisez +``:term:`dictionary``` en ``:term:`dictionaire ```. + +Comme le glossaire est déjà traduit, il y a forcément une correspondance à chaque +terme que vous pouvez rencontrer. + +Style +~~~~~ + +Une bonne traduction est une traduction qui transcrit fidèlement l'idée originelle +en français, sans rien ajouter ni enlever au fond, tout en restant claire, concise et +agréable à lire. Les traductions mot-à-mot sont à proscrire et il est permis — même +conseillé — d'intervertir des propositions ou de réarranger des phrases de la +documentation anglaise, si le rythme l'exige. Il faut aussi chercher des +équivalents français aux termes techniques et aux idiotismes rencontrés, et prendre +garde aux anglicismes. Utilisation du futur ~~~~~~~~~~~~~~~~~~~~ @@ -249,28 +334,22 @@ Dans un souci de lisibilité et en accord avec la préconisation de l'Académie française, nous utilisons le masculin pour indiquer un genre neutre. Par exemple : l'utilisateur ou le lecteur. -Style -~~~~~ - -Une bonne traduction est une traduction qui transcrit fidèlement l'idée originelle -en français, sans rien ajouter ni enlever au fond, tout en restant claire, concise et -agréable à lire. Les traductions mot-à-mot sont à proscrire et il est permis — même -conseillé — d'intervertir des propositions ou de réarranger des phrases de la -documentation anglaise, si le rythme l'exige. Il faut aussi chercher des -équivalents français aux termes techniques et aux idiotismes rencontrés, et prendre -garde aux anglicismes. - Glossaire ~~~~~~~~~ -Afin d'assurer la cohérence de la traduction, voici quelques propositions et -rappels pour les termes fréquents à traduire. +Afin d'assurer la cohérence de la traduction, voici quelques +termes fréquents déjà traduits. Une liste blanche de noms propres, comme « Guido », +« C99 » ou de certains anglicismes comme « sérialisable » ou « implémentation», +est stockée dans le fichier « dict » à la racine du projet. Vous pouvez +y ajouter une entrée si cela est nécessaire. +Si vous devez *absolument* utiliser un mot anglais, mettez-le en italique +(entouré par des astérisques). Pour trouver facilement comment un terme est déjà traduit dans la documentation, vous pouvez utiliser `pogrep`_. ========================== =============================================== -Terme Traduction proposée +Terme Traduction ========================== =============================================== -like -compatible abstract data type type abstrait @@ -307,8 +386,8 @@ i.e. c.-à-d. (on n'utilise pas l'anglicisme « i.e. », identifier identifiant immutable immuable import importation -index indice (en particulier quand on parle de chaînes de - caractères) +index indice (en particulier quand on parle de chaînes + de caractères) installer installateur interpreter interpréteur library bibliothèque @@ -332,10 +411,11 @@ simple quote guillemet simple socket connecteur ou interface de connexion statement instruction subprocess sous-processus -support prendre en charge, implémenter (« supporter » n'a - pas le même sens en français) +support prendre en charge, implémenter (« supporter » + n'a pas le même sens en français) specify définir, préciser (plutôt que « spécifier ») -typically normalement, habituellement, comme d'habitude (plutôt que « typiquement ») +typically normalement, habituellement, comme d'habitude + (plutôt que « typiquement ») thread fil d'exécution traceback trace d'appels, trace de pile tuple n-uplet @@ -343,8 +423,8 @@ underscore tiret bas, *underscore* whitespace caractère d'espacement ========================== =============================================== -Caractères spéciaux -------------------- +Caractères spéciaux et typographie +---------------------------------- La touche de composition ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -525,6 +605,7 @@ Powrap | Installez-le à l'aide de *pip* (``pip install powrap``). | `Lien vers le dépôt `__ + Ressources de traduction ------------------------ @@ -554,6 +635,7 @@ L'utilisation de traducteurs automatiques comme `DeepL https://www.deepl.com/` o Les traductions générées sont très souvent à retravailler, ils ignorent les règles énoncées sur cette page et génèrent une documentation au style très « lourd ». + Simplification des diffs git ---------------------------- @@ -581,9 +663,10 @@ ce qui suit après vous être assuré que ``~/.local/bin/`` se trouve dans votre git config diff.podiff.textconv podiff -Pas d'inquiétude, cela ne change la façon dont Git voit les changements que sur +Pas d'inquiétude, cela ne change la façon dont Git affiche les changements que sur les fichiers de la traduction, sans incidence sur les autres. + Maintenance ----------- @@ -607,8 +690,8 @@ Ceci évite de télécharger tout l'historique (inutile pour générer la documentation) mais récupère néanmoins toutes les branches. -Fusionner les fichiers *pot* de CPython -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Fusion des fichiers *pot* de CPython +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -623,16 +706,25 @@ Trouver les chaînes de caractères *fuzzy* make fuzzy -Lancer un *build* en local -~~~~~~~~~~~~~~~~~~~~~~~~~~ +*build* local +~~~~~~~~~~~~~ .. code-block:: bash make -Synchroniser la traduction avec Transifex -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Serveur de documentation en local +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + make serve + + + +Synchronisation de la traduction avec Transifex +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Vous aurez besoin de ``transifex-client`` et ``powrap``, depuis PyPI.